@paulstinchcombe/gasless-nft-tx 0.4.8 → 0.5.0

package/README.md

@@ -1,405 +1,673 @@
-# 📦 Gasless NFT Transaction Library
+# Gasless NFT Transactions Library
 
-A robust, production-ready TypeScript library that enables **gasless NFT transactions** using SimpleAccount operations. Perfect for Next.js backends, Node.js applications, and any TypeScript/JavaScript environment.
+A comprehensive TypeScript library for deploying and managing KAMI NFT contracts with truly gasless transactions using EIP-4337 Account Abstraction and SimpleAccount.
 
-## 🎯 Features
+## 🎯 What This Library Does
 
--   **🎉 Completely Gasless NFT Transactions**: Users pay zero gas fees - SimpleAccount pays all gas
--   **🏦 SimpleAccount Operations**: Deploy, mint, and manage NFTs through funded SimpleAccount
--   **🚀 Auto-Deploy Everything**: Automatically deploys SimpleAccountFactory and SimpleAccount when needed
--   **🎨 NFT Operations**: Deploy, mint, and buy NFTs without any gas fees
--   **🔍 NFT Discovery**: Find ALL NFTs owned by any EOA across ALL contracts
--   **🔧 Flexible Deployment**: Deploy NFTs with SimpleAccount as owner from the start
--   **📦 Batch Operations**: Execute multiple operations across different contracts
--   **💰 Backend Minting**: Alternative backend-controlled minting for maximum reliability
--   **🔢 Quantity Support**: Batch minting and purchasing with quantity parameters
--   **📘 TypeScript First**: Full type safety with comprehensive IntelliSense support
--   **🎭 Multiple NFT Standards**: Support for ERC-721, ERC-721A, and ERC-1155
--   **🆕 Enhanced Mint Results**: Get tokenId, recipient, and contract info automatically from mints
--   **✅ Well Tested**: Comprehensive test suite with vitest
--   **🛡️ Robust Error Handling**: Automatic retry and recovery mechanisms
--   **🔮 Deterministic Addresses**: Predictable SimpleAccount addresses using CREATE2
+-   ✅ **Truly Gasless Deployments** - Deploy NFT contracts where SimpleAccount pays all gas
+-   ✅ **Three NFT Standards** - Support for KAMI721C (ERC721), KAMI721AC (ERC721A), and KAMI1155C (ERC1155)
+-   ✅ **Creator Features** - Built-in royalties, rentals, and platform fees
+-   ✅ **Library Linking** - Automatic handling of Solidity library dependencies
+-   ✅ **Type-Safe** - Full TypeScript support with comprehensive type definitions
 
-## ⚠️ Important: Update to v0.4.4+
+## 📋 Table of Contents
 
-If you're deploying KAMI libraries and got "Contract artifact not found" errors, update immediately:
+-   [Quick Start](#quick-start)
+-   [Complete Setup Guide](#complete-setup-guide)
+    -   [Step 1: Environment Setup](#step-1-environment-setup)
+    -   [Step 2: Deploy SimpleAccount](#step-2-deploy-simpleaccount)
+    -   [Step 3: Deploy ContractDeployer](#step-3-deploy-contractdeployer)
+    -   [Step 4: Deploy KAMI Libraries](#step-4-deploy-kami-libraries)
+    -   [Step 5: Deploy Your NFT Contract](#step-5-deploy-your-nft-contract)
+-   [Contract Types](#contract-types)
+-   [API Reference](#api-reference)
+-   [Gas Costs](#gas-costs)
+-   [Examples](#examples)
+-   [Next.js Deployment](#nextjs-deployment)
+-   [Troubleshooting](#troubleshooting)
+
+## Quick Start
+
+```bash
+# Install
+npm install your-package-name
+
+# Set environment variables
+export PRIVATE_KEY="0x..."
+export SIMPLE_ACCOUNT_ADDRESS="0x..."
+
+# Deploy infrastructure (one-time setup)
+npx tsx examples/gasless-deployment-complete.ts
+export CONTRACT_DEPLOYER_ADDRESS="0x..."
+
+# Deploy libraries (one-time setup)
+npx tsx examples/deploy-shared-libraries-example.ts
+
+# Deploy your NFT contract (gasless!)
+npx tsx examples/true-gasless-deployment.ts
+```
+
+## Complete Setup Guide
+
+### Prerequisites
+
+-   Node.js 18+ and npm/pnpm
+-   An Ethereum wallet with private key
+-   ~0.05 ETH on Base Sepolia testnet for initial setup
+
+### Step 1: Environment Setup
+
+Create a `.env` file in your project:
+
+```bash
+# Your EOA private key (for signing transactions)
+PRIVATE_KEY="0x1234567890abcdef..."
+
+# RPC endpoint (Base Sepolia testnet)
+RPC_URL="https://sepolia.base.org"
+```
+
+### Step 2: Deploy SimpleAccount
+
+SimpleAccount is an EIP-4337 smart contract wallet that will pay for all gas.
+
+#### Option A: Using the Library
+
+```typescript
+import { createSimpleAccount, deploySimpleAccountFactory } from 'your-package-name';
+import { privateKeyToAccount } from 'viem/accounts';
+
+const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
+
+// 1. Deploy SimpleAccountFactory (if not already deployed)
+const factory = await deploySimpleAccountFactory({
+	rpcUrl: 'https://sepolia.base.org',
+	deployerPrivateKey: process.env.PRIVATE_KEY as `0x${string}`,
+});
+
+console.log('Factory:', factory.factoryAddress);
+
+// 2. Create SimpleAccount for your EOA
+const simpleAccount = await createSimpleAccount({
+	rpcUrl: 'https://sepolia.base.org',
+	factoryAddress: factory.factoryAddress,
+	owner: account.address,
+	deployerPrivateKey: process.env.PRIVATE_KEY as `0x${string}`,
+});
+
+console.log('SimpleAccount:', simpleAccount.accountAddress);
+```
+
+#### Option B: Using Existing SimpleAccount
+
+If you already have a SimpleAccount deployed:
+
+```bash
+export SIMPLE_ACCOUNT_ADDRESS="0xYourSimpleAccountAddress"
+```
+
+#### Funding SimpleAccount
+
+SimpleAccount needs ETH to pay for gas:
 
 ```bash
-npm install @paulstinchcombe/gasless-nft-tx@^0.4.4
+# Send 0.05 ETH to your SimpleAccount
+cast send $SIMPLE_ACCOUNT_ADDRESS \
+  --value 0.05ether \
+  --private-key $PRIVATE_KEY \
+  --rpc-url https://sepolia.base.org
 ```
 
-**Fixed:** KAMI artifacts now properly included in npm package. See [Migration Guide](./docs/MIGRATION_v0.4.4.md).
+**Update `.env`:**
 
-### Next.js Users: Additional Step Required
+```bash
+SIMPLE_ACCOUNT_ADDRESS="0x..."
+```
+
+### Step 3: Deploy ContractDeployer
+
+ContractDeployer is a helper contract that enables gasless deployments via SimpleAccount.
+
+**Why needed?** SimpleAccount's `execute()` function can't deploy contracts directly. ContractDeployer acts as a helper that SimpleAccount calls, which then deploys your contracts using the CREATE opcode.
+
+```bash
+npx tsx examples/gasless-deployment-complete.ts
+```
+
+**Expected Output:**
+
+```
+✅ Configuration validated
+💰 SimpleAccount balance: 0.050000 ETH
+
+🔧 Deploying ContractDeployer helper contract...
+⚠️  NOTE: This deployment requires gas from your EOA (not gasless)
+   ContractDeployer is a one-time deployment that enables all future gasless deployments
 
-If using Next.js and still getting artifact errors after updating, see:
+   Transaction: 0xabc123...
+✅ ContractDeployer deployed at: 0xDEF456...
+💾 Save this address for future use!
+📝 This was a one-time cost. All future KAMI deployments will be gasless!
+```
 
--   **[Complete API Route Example](./docs/NEXTJS_API_DEPLOYMENT_EXAMPLE.md)** - Full working example with debugging
--   **[Next.js Artifacts Fix](./docs/NEXTJS_ARTIFACTS_FIX.md)** - Solutions for artifact loading issues
--   **[Complete Dockerfile](./docs/NEXTJS_COMPLETE_DOCKERFILE.md)** - Ready-to-use Dockerfile for Docker
+**Cost:** ~0.001 ETH from your EOA (one-time only)
 
-You need to configure Next.js to copy artifacts to the build output and ensure all environment variables are properly set.
+**Update `.env`:**
 
-## 🎊 What's New in v0.4.0 - Per-Token Pricing & Enhanced APIs!
+```bash
+CONTRACT_DEPLOYER_ADDRESS="0x..."
+```
 
-### 🔥 Major API Improvements
+### Step 4: Deploy KAMI Libraries
 
--   **Per-Token Pricing**: Each token can have its own price (no more global mintPrice!)
--   **Individual Token URIs**: Set unique metadata for each token
--   **Enhanced Mint Results**: Mint operations now return tokenId and recipient info automatically ✨
--   **Enhanced Security**: Explicit seller/renter parameters prevent impersonation
--   **Better Flexibility**: Dynamic pricing strategies for NFT marketplaces
--   **✅ 90 Tests Passing**: Comprehensive test coverage for all handlers
+KAMI contracts use five shared libraries. Deploy them once and reuse for all NFT contracts.
 
-⚠️ **Breaking Changes**: If upgrading from v0.3.x, see **[Migration Guide](./docs/KAMI_API_CHANGES_v0.4.0.md)**
+```bash
+npx tsx examples/deploy-shared-libraries-example.ts
+```
 
-### 🆕 KAMI NFT Support (All Gasless!)
+**Expected Output:**
 
--   **Three Contract Types**: KAMI721C, KAMI721AC, KAMI1155C
--   **Fully Gasless Operations**: Minting, rentals, sales, royalties - all via SimpleAccount
--   **Shared Library System**: Deploy libraries once, reuse forever
--   **💰 44-66% Gas Savings**: Save significant costs at scale with library sharing
--   **Advanced Features**: Built-in royalties, rentals, platform commissions
+```
+📚 Deploying all KAMI libraries via SimpleAccount (gasless)...
+🚀 Deploying KamiNFTCore...
+   Transaction: 0x...
+✅ Contract deployed at: 0x...
+
+[... repeats for all 5 libraries ...]
+
+✅ All libraries deployed successfully!
+💾 SAVE THESE ADDRESSES - Reuse them for all future NFT deployments:
+{
+  "kamiNFTCore": "0x...",
+  "kamiPlatform": "0x...",
+  "kamiRoyalty": "0x...",
+  "kamiRental": "0x...",
+  "kamiTransfer": "0x..."
+}
+```
+
+**Cost:** ~0.008 ETH from SimpleAccount (one-time, reusable)
+
+**Update `.env`:**
+
+```bash
+KAMI_NFT_CORE="0x..."
+KAMI_PLATFORM="0x..."
+KAMI_ROYALTY="0x..."
+KAMI_RENTAL="0x..."
+KAMI_TRANSFER="0x..."
+```
+
+### Step 5: Deploy Your NFT Contract
+
+Now deploy any KAMI NFT contract completely gaslessly!
+
+#### Deploy KAMI721C (Standard ERC721)
+
+```bash
+npx tsx examples/true-gasless-deployment.ts
+```
+
+#### Deploy KAMI721AC (ERC721A with Batch Minting)
+
+```bash
+npx tsx examples/deploy-kami721ac-gasless.ts
+```
+
+#### Deploy KAMI1155C (ERC1155 Multi-Token)
+
+```bash
+npx tsx examples/deploy-kami1155c-gasless.ts
+```
 
-📊 **[See Gas Savings Analysis](./docs/KAMI_GAS_SAVINGS_ANALYSIS.md)** - Detailed cost breakdown and ROI
+**Expected Output:**
 
-### Previous Features
+```
+🚀 Deploying KAMI721C gaslessly with library linking...
+   Name: My NFT Collection (MNFT)
+   Mint Price: 0.001 ETH
+
+📚 Linking libraries to KAMI721C bytecode...
+✅ Bytecode linked, length: 45678 bytes
+
+🚀 Deploying contract gaslessly via ContractDeployer...
+📤 Sending deployment transaction via SimpleAccount...
+   Transaction: 0x...
+✅ Contract deployed at: 0x...
+
+🎉 KAMI721C deployed successfully (gasless)!
+📍 Address: 0x...
+👤 Owner: 0x... (SimpleAccount)
+🔗 Explorer: https://sepolia.basescan.org/address/0x...
+```
 
--   🆕 **SimpleAccount Owner Deployment**: Deploy NFTs with SimpleAccount as owner from the start
--   🎯 **Immediate Gasless Minting**: Mint NFTs immediately after deployment through SimpleAccount
--   🔍 **Comprehensive NFT Discovery**: Find ALL NFTs owned by any EOA across ALL contracts
--   🔄 **Streamlined Workflow**: One-step deployment and minting process
--   🏦 **Funded SimpleAccount**: SimpleAccount pays its own gas for truly gasless user experience
--   🔧 **Backend Minting**: Alternative approach for maximum reliability
+**Cost:** ~0.015 ETH from SimpleAccount (per deployment)
 
-## 🚀 Installation
+**Save the contract address:**
 
 ```bash
-npm install @paulstinchcombe/gasless-nft-tx
-# or
-pnpm add @paulstinchcombe/gasless-nft-tx
-# or
-yarn add @paulstinchcombe/gasless-nft-tx
+export KAMI721C_ADDRESS="0x..."
 ```
 
-## 🌟 What Makes This Special?
+## Contract Types
+
+### KAMI721C - Standard ERC721 with Creator Features
+
+**Use for:**
+
+-   Standard NFT collections
+-   Art projects
+-   Collectibles
+-   Small to medium collections (< 1,000 NFTs)
 
--   **🎯 SimpleAccount-First**: Built around SimpleAccount operations for reliability
--   **💰 Truly Gasless**: Users never pay gas - SimpleAccount handles everything
--   **🔧 Two Approaches**: Choose between SimpleAccount operations or backend minting
--   **📦 Production Ready**: Battle-tested with comprehensive error handling
--   **🎨 Developer Friendly**: Clean API with full TypeScript support
+**Features:**
 
-## 📖 Quick Start
+-   ✅ ERC721 standard compliance
+-   ✅ Creator royalties (EIP-2981)
+-   ✅ Rental system
+-   ✅ Platform fees
+-   ✅ Maximum compatibility
 
-### 1. SimpleAccount Operations (Recommended)
+**Deployment:**
 
 ```typescript
-import { createSimpleAccountOperations } from '@paulstinchcombe/gasless-nft-tx';
+import { KamiGaslessDeployerWithLibraries, KAMI721CParams } from 'your-package-name';
+import { parseEther, Address } from 'viem';
 
-// Create SimpleAccount operations instance
-const ops = createSimpleAccountOperations({
+const deployer = new KamiGaslessDeployerWithLibraries({
 	rpcUrl: 'https://sepolia.base.org',
-	ownerPrivateKey: '0x...', // EOA private key for funding
-	simpleAccountAddress: '0x...', // Your SimpleAccount address
-	deployerAddress: '0x...', // SimpleDeployer contract address
+	ownerPrivateKey: process.env.PRIVATE_KEY as `0x${string}`,
+	simpleAccountAddress: process.env.SIMPLE_ACCOUNT_ADDRESS as Address,
+	contractDeployerAddress: process.env.CONTRACT_DEPLOYER_ADDRESS as Address,
+	libraries: {
+		kamiNFTCore: process.env.KAMI_NFT_CORE as Address,
+		kamiPlatform: process.env.KAMI_PLATFORM as Address,
+		kamiRoyalty: process.env.KAMI_ROYALTY as Address,
+		kamiRental: process.env.KAMI_RENTAL as Address,
+		kamiTransfer: process.env.KAMI_TRANSFER as Address,
+	},
 });
 
-// Deploy NFT with SimpleAccount as owner
-const deployResult = await ops.deployNftContract(bytecode, {
-	name: 'My NFT',
+const params: KAMI721CParams = {
+	paymentToken: '0x0000000000000000000000000000000000000000', // Native ETH
+	name: 'My NFT Collection',
 	symbol: 'MNFT',
-	baseURI: 'https://api.example.com/metadata/',
-	maxSupply: 1000n,
-});
+	baseTokenURI: 'ipfs://QmYourBaseURI/',
+	initialMintPrice: parseEther('0.001'), // 0.001 ETH per mint
+	platformAddress: process.env.SIMPLE_ACCOUNT_ADDRESS as Address,
+	platformCommissionPercentage: 250, // 2.5%
+};
+
+const result = await deployer.deployKAMI721C(params);
+console.log('Deployed at:', result.contractAddress);
+```
 
-if (deployResult.success) {
-	// Immediately mint NFTs gaslessly
-	const mintResult = await ops.mintNft(
-		deployResult.contractAddress!,
-		userAddress,
-		1n // Token ID
-	);
-}
+### KAMI721AC - ERC721A with Batch Minting
+
+**Use for:**
+
+-   Large NFT collections (1k-10k+ NFTs)
+-   Projects with batch minting needs
+-   Gas-efficient launches
+-   Generative art projects
+
+**Features:**
+
+-   ✅ ERC721A (batch minting optimization)
+-   ✅ Much cheaper batch mints (~90% gas savings)
+-   ✅ All Creator features (royalties, rentals)
+-   ✅ Perfect for large drops
+
+**Deployment:**
+
+```typescript
+const params: KAMI721ACParams = {
+	paymentToken: '0x0000000000000000000000000000000000000000',
+	name: 'Creator Collection',
+	symbol: 'CNFT',
+	baseTokenURI: 'ipfs://QmYourBaseURI/',
+	initialMintPrice: parseEther('0.001'),
+	platformAddress: process.env.SIMPLE_ACCOUNT_ADDRESS as Address,
+	platformCommissionPercentage: 250,
+};
+
+const result = await deployer.deployKAMI721AC(params);
 ```
 
-### 2. NFT Discovery (NEW!)
+**Batch Minting Example:**
+Mint 10 NFTs for nearly the same gas cost as minting 1!
+
+### KAMI1155C - ERC1155 Multi-Token
+
+**Use for:**
+
+-   Gaming projects (items, currencies, characters)
+-   Multi-edition artworks
+-   Mixed fungible/non-fungible tokens
+-   Membership tiers
+
+**Features:**
+
+-   ✅ ERC1155 multi-token standard
+-   ✅ Multiple token IDs in one contract
+-   ✅ Fungible and non-fungible support
+-   ✅ Very gas efficient
+-   ✅ All Creator features
+
+**Deployment:**
 
 ```typescript
-import { createNftListingOperations } from '@paulstinchcombe/gasless-nft-tx';
+const params: KAMI1155CParams = {
+	paymentToken: '0x0000000000000000000000000000000000000000',
+	baseTokenURI: 'ipfs://QmYourBaseURI/{id}.json', // {id} auto-replaced
+	initialMintPrice: parseEther('0.001'),
+	platformAddress: process.env.SIMPLE_ACCOUNT_ADDRESS as Address,
+	platformCommissionPercentage: 250,
+};
+
+const result = await deployer.deployKAMI1155C(params);
+```
 
-// Create NFT listing instance
-const nftListing = createNftListingOperations({
-	rpcUrl: 'https://sepolia.base.org',
-	includeMetadata: true,
-});
+## API Reference
+
+### KamiGaslessDeployerWithLibraries
+
+Main class for deploying KAMI contracts gaslessly.
+
+#### Constructor
+
+```typescript
+constructor(config: GaslessDeployConfig)
+```
+
+**Parameters:**
+
+-   `rpcUrl` (string): RPC endpoint URL
+-   `ownerPrivateKey` (`0x${string}`): Private key for signing
+-   `simpleAccountAddress` (Address): Your SimpleAccount address
+-   `contractDeployerAddress` (Address): ContractDeployer helper address
+-   `libraries` (LibraryAddresses): Deployed library addresses
+
+#### Methods
+
+##### deployKAMI721C
+
+```typescript
+async deployKAMI721C(params: KAMI721CParams): Promise<DeploymentResult>
+```
+
+Deploy a KAMI721C contract (ERC721 + Creator).
 
-// Discover ALL NFTs owned by an address across ALL contracts
-const result = await nftListing.discoverAllNftsForOwner('0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6');
+**Parameters:**
 
-if (result.success) {
-	console.log(`Found ${result.totalCount} NFTs across ALL contracts`);
+-   `paymentToken` (Address): Payment token address (0x0 for ETH)
+-   `name` (string): NFT collection name
+-   `symbol` (string): NFT collection symbol
+-   `baseTokenURI` (string): Base URI for token metadata
+-   `initialMintPrice` (bigint): Price per mint in wei
+-   `platformAddress` (Address): Platform fee recipient
+-   `platformCommissionPercentage` (number): Platform fee (250 = 2.5%)
 
-	// Group by contract
-	const byContract = result.tokens?.reduce((acc, token) => {
-		const contract = token.contractAddress;
-		if (!acc[contract]) acc[contract] = [];
-		acc[contract].push(token);
-		return acc;
-	}, {} as Record<string, typeof result.tokens>);
+**Returns:**
 
-	Object.entries(byContract || {}).forEach(([contract, tokens]) => {
-		console.log(`Contract ${contract}: ${tokens.length} tokens`);
-	});
+```typescript
+{
+  success: boolean;
+  contractAddress?: Address;
+  transactionHash?: string;
+  error?: string;
 }
 ```
 
-### 3. Backend Minting (Alternative)
+##### deployKAMI721AC
 
 ```typescript
-import { createBackendMintHandler } from '@paulstinchcombe/gasless-nft-tx';
+async deployKAMI721AC(params: KAMI721ACParams): Promise<DeploymentResult>
+```
 
-// Create backend mint handler
-const mintHandler = createBackendMintHandler({
-	rpcUrl: 'https://sepolia.base.org',
-	nftContractAddress: '0x...', // Deployed NFT contract
-	ownerPrivateKey: '0x...', // Backend EOA private key
-	simpleAccountAddress: '0x...', // SimpleAccount address
-	chain: baseSepolia,
-});
+Deploy a KAMI721AC contract (ERC721A + Creator).
 
-// Mint NFT (backend pays gas)
-const mintResult = await mintHandler.mintNft({
-	to: userAddress,
-	tokenId: 1n,
-	quantity: 1n,
-});
+Same parameters as KAMI721C.
+
+##### deployKAMI1155C
+
+```typescript
+async deployKAMI1155C(params: KAMI1155CParams): Promise<DeploymentResult>
 ```
 
-### 4. KAMI NFT Operations with Enhanced Mint Results (NEW in v0.4.0!)
+Deploy a KAMI1155C contract (ERC1155 + Creator).
+
+**Parameters:**
+
+-   `paymentToken` (Address): Payment token address
+-   `baseTokenURI` (string): Base URI with {id} placeholder
+-   `initialMintPrice` (bigint): Price per token in wei
+-   `platformAddress` (Address): Platform fee recipient
+-   `platformCommissionPercentage` (number): Platform fee percentage
+
+##### getBalance
 
 ```typescript
-import { KAMI721CSimpleAccountHandler } from '@paulstinchcombe/gasless-nft-tx';
-import type { KAMI721CMintOperationResult } from '@paulstinchcombe/gasless-nft-tx';
+async getBalance(): Promise<bigint>
+```
 
-// Create KAMI721C handler
-const handler = new KAMI721CSimpleAccountHandler({
-	rpcUrl: 'https://sepolia.base.org',
-	ownerPrivateKey: '0x...', // Your private key
-	simpleAccountAddress: '0x...', // Your SimpleAccount
-	kamiContractAddress: '0x...', // KAMI721C contract
-});
+Get SimpleAccount's current ETH balance.
+
+### Type Definitions
+
+```typescript
+// Library addresses (shared by all contracts)
+interface LibraryAddresses {
+	kamiNFTCore: Address;
+	kamiPlatform: Address;
+	kamiRoyalty: Address;
+	kamiRental: Address;
+	kamiTransfer: Address;
+}
 
-// Mint NFT and get token information immediately!
-const result: KAMI721CMintOperationResult = await handler.mint(
-	'0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb1', // recipient
-	1000000n, // price (1 USDC with 6 decimals)
-	'ipfs://QmExampleHash' // token URI
-);
-
-if (result.success && result.tokenId) {
-	console.log('✅ Minted successfully!');
-	console.log(`   Token ID: ${result.tokenId}`);
-	console.log(`   Recipient: ${result.recipient}`);
-	console.log(`   Contract: ${result.contractAddress}`);
-	console.log(`   Transaction: ${result.transactionHash}`);
-
-	// Use tokenId immediately for subsequent operations!
-	await handler.setPrice(result.tokenId, 2000000n);
-	await handler.setTokenURI(result.tokenId, 'ipfs://QmUpdatedHash');
-
-	// Save to database
-	await db.nfts.create({
-		tokenId: result.tokenId.toString(),
-		contractAddress: result.contractAddress,
-		recipient: result.recipient,
-		transactionHash: result.transactionHash,
-	});
+// Deployment result
+interface DeploymentResult {
+	success: boolean;
+	contractAddress?: Address;
+	transactionHash?: string;
+	error?: string;
 }
 ```
 
-**All KAMI mint operations now return tokenId automatically:**
+## Gas Costs
 
--   ✅ `KAMI721C.mint()` - Returns tokenId, recipient, contract address
--   ✅ `KAMI721AC.mint()` - Returns tokenId, recipient, contract address
--   ✅ `KAMI721AC.batchClaimFor()` - Returns tokenIds array, recipients array
--   ✅ `KAMI1155C.mint()` - Returns tokenId, amount, recipient, contract address
--   ✅ `KAMI1155C.mintBatch()` - Returns tokenIds array, amounts array, recipients array
+All costs are estimates on Base Sepolia. Mainnet costs may vary.
 
-📖 **See [Enhanced Mint Results Guide](./docs/MINT_RESULTS_GUIDE.md) for complete documentation.**
+### One-Time Setup Costs
 
-## 📚 Documentation
+| Item                 | Who Pays      | Cost       | Frequency     |
+| -------------------- | ------------- | ---------- | ------------- |
+| **SimpleAccount**    | EOA           | ~0.005 ETH | Once per user |
+| **ContractDeployer** | EOA           | ~0.001 ETH | Once ever     |
+| **KAMI Libraries**   | SimpleAccount | ~0.008 ETH | Once ever     |
 
-### Core Guides
+**Total Setup**: ~0.014 ETH (one-time)
 
--   **[SimpleAccount Guide](./docs/SIMPLE_ACCOUNT_GUIDE.md)** - Complete guide to SimpleAccount operations
--   **[SimpleAccount Owner Deployment](./docs/SIMPLEACCOUNT_OWNER_DEPLOYMENT.md)** - Deploy NFTs with SimpleAccount as owner
--   **[NFT Listing Guide](./docs/NFT_LISTING_GUIDE.md)** - Discover and list NFTs owned by any EOA
--   **[Backend Mint Guide](./docs/BACKEND_MINT_GUIDE.md)** - Alternative backend-controlled minting
--   **[Quick Reference](./docs/QUICK_REFERENCE.md)** - Quick start and common patterns
+### Per-Deployment Costs
 
-### Advanced Topics
+| Contract Type | Who Pays      | Cost       | Notes           |
+| ------------- | ------------- | ---------- | --------------- |
+| **KAMI721C**  | SimpleAccount | ~0.015 ETH | Standard ERC721 |
+| **KAMI721AC** | SimpleAccount | ~0.015 ETH | ERC721A         |
+| **KAMI1155C** | SimpleAccount | ~0.015 ETH | ERC1155         |
 
--   **[EIP-7702 vs SimpleAccount Comparison](./docs/EIP7702_VS_SIMPLEACCOUNT_COMPARISON.md)** - Detailed comparison of approaches
--   **[Gas Optimization](./docs/GAS_OPTIMIZATION_GUIDE.md)** - Optimize gas usage and costs
--   **[Library Overview](./docs/LIBRARY_OVERVIEW.md)** - Architecture and design decisions
--   **[Complete Workflow](./docs/COMPLETE_WORKFLOW_PAULSNFT.md)** - End-to-end workflow example
+**After Setup**: Deploy unlimited contracts for ~0.015 ETH each (from SimpleAccount)
 
-## 🔧 API Reference
+### Gasless Benefits
 
-### `createSimpleAccountOperations(config)`
+-   ✅ **Users pay nothing** - All gas paid by SimpleAccount
+-   ✅ **EOA only signs** - No ETH needed in user wallet
+-   ✅ **True gasless experience** - Best UX possible
 
-Create a SimpleAccount operations instance for gasless transactions.
+## Examples
 
-**Parameters:**
+All examples are in the `examples/` directory:
 
--   `config.rpcUrl` (string): Ethereum RPC endpoint URL
--   `config.ownerPrivateKey` (Hex): EOA private key for funding and management
--   `config.simpleAccountAddress` (Address): SimpleAccount address
--   `config.deployerAddress` (Address): SimpleDeployer contract address
+### Infrastructure Setup
 
-**Returns:** `SimpleAccountOperations` instance
+-   `gasless-deployment-complete.ts` - Deploy ContractDeployer
+-   `deploy-shared-libraries-example.ts` - Deploy KAMI libraries
+-   `check-library-deployment.ts` - Verify library deployments
 
-### `deployNftContract(bytecode, constructorArgs, salt?)`
+### Contract Deployment
 
-Deploy an NFT contract with SimpleAccount as owner.
+-   `true-gasless-deployment.ts` - Deploy KAMI721C
+-   `deploy-kami721ac-gasless.ts` - Deploy KAMI721AC
+-   `deploy-kami1155c-gasless.ts` - Deploy KAMI1155C
 
-**Parameters:**
+### SimpleAccount Setup
 
--   `bytecode` (Hex): Compiled NFT contract bytecode
--   `constructorArgs` (NftConstructorArgs): Constructor arguments
--   `salt` (Hex, optional): Salt for deterministic deployment
+-   `deploy-simple-deployer.ts` - Deploy SimpleAccountFactory
+-   `fund-simpleaccount.ts` - Fund SimpleAccount with ETH
 
-**Returns:** `Promise<DeployResult>` - Deployment result with contract address
+## Next.js Deployment
 
-### `mintNft(contractAddress, to, tokenId)`
+If you're using this library in a Next.js API route, you'll encounter artifact loading issues. See the complete guide:
 
-Mint an NFT through SimpleAccount.
+👉 **[Next.js Deployment Guide](docs/NEXTJS_DEPLOYMENT.md)**
 
-**Parameters:**
+**Quick Summary**: The library loads contract artifacts using `fs.readFileSync()`, which doesn't work in Next.js production builds. You need to:
 
--   `contractAddress` (Address): NFT contract address
--   `to` (Address): Recipient address
--   `tokenId` (bigint): Token ID to mint
+1. **Use the custom wrapper** (recommended) - See guide for ready-to-use `NextJsKamiDeployer` class
+2. **Or configure Next.js** - Update `next.config.js` to include artifacts
+3. **Or use Docker** - Ensure artifacts are copied to container
 
-**Returns:** `Promise<MintResult>` - Mint result with transaction hash
+The guide includes complete code examples and troubleshooting steps.
 
-## 📁 Examples
+## Troubleshooting
 
-Check the `examples/` directory for complete working examples:
+### Next.js "ENOENT: no such file or directory" Error
 
-### KAMI NFT Examples
+**Symptoms**: Error opening KAMI721C.json artifact file in production
 
--   `mint-with-tokenid-example.ts` - 🆕 **Minting with enhanced token info (all KAMI handlers)**
--   `check-library-deployment.ts` - 🆕 **Verify KAMI libraries are deployed**
--   `nextjs-kami-config.ts` - 🆕 **Next.js helper for loading libraries from environment**
--   `kami-payment-example.ts` - Complete KAMI payment flow with ERC20 tokens
--   `deploy-shared-libraries-example.ts` - Deploy and share KAMI libraries (44-66% gas savings)
+**Solution**: See [Next.js Deployment Guide](docs/NEXTJS_DEPLOYMENT.md) for complete fix with ready-to-use wrapper class.
 
-### General Examples
+**Quick Fix**: Use the `NextJsKamiDeployer` wrapper that imports artifacts directly instead of loading from disk.
 
--   `test-simpleaccount-operations.ts` - Basic SimpleAccount operations
--   `deploy-with-simpleaccount.ts` - Deploy NFT with SimpleAccount as owner
--   `fund-simpleaccount.ts` - Fund SimpleAccount with ETH
--   `list-nfts-example.ts` - Complete NFT discovery and listing examples
--   `backend-mint-api.ts` - Backend minting API example
+### Contract Not Appearing on BaseScan
 
-## 🧪 Testing
+**Wait 1-2 minutes** for block explorer indexing.
 
-```bash
-# Run tests
-npm test
+If still not visible:
+
+1. Check transaction on BaseScan: `https://sepolia.basescan.org/tx/YOUR_TX`
+2. Look for "Internal Transactions" tab
+3. Verify "ContractDeployed" event in logs
+4. Confirm ContractDeployer is deployed correctly
+
+### "Insufficient Balance" Error
 
-# Run tests with coverage
-npm run test:coverage
+```bash
+# Check SimpleAccount balance
+cast balance $SIMPLE_ACCOUNT_ADDRESS --rpc-url https://sepolia.base.org
+
+# Fund if needed
+cast send $SIMPLE_ACCOUNT_ADDRESS \
+  --value 0.03ether \
+  --private-key $PRIVATE_KEY \
+  --rpc-url https://sepolia.base.org
 ```
 
-## 🔧 Development
+### "ContractDeployer not deployed" Error
+
+Deploy ContractDeployer first:
 
 ```bash
-# Install dependencies
-pnpm install
+npx tsx examples/gasless-deployment-complete.ts
+```
+
+### "Library addresses invalid" Error
 
-# Build the library
-pnpm run build
+Verify all libraries are deployed:
 
-# Watch mode for development
-pnpm run dev
+```bash
+npx tsx examples/check-library-deployment.ts
 ```
 
-## 🛠️ Troubleshooting
+### Deployment Transaction Reverts
+
+1. **Check SimpleAccount has enough ETH** (~0.02 ETH minimum)
+2. **Verify all library addresses** are correct and deployed
+3. **Check ContractDeployer address** is valid
+4. **Look at revert reason** on BaseScan transaction page
+
+### "Invalid byte sequence" Error
 
-### Common Issues
+This usually means:
 
-#### ❌ "Insufficient SimpleAccount balance"
+-   Bytecode has formatting issues (spaces in hex)
+-   Update to latest version of the library
 
--   **Solution**: Fund the SimpleAccount using `fund-simpleaccount.ts` or transfer ETH to it
+## Architecture
+
+### How It Works
+
+```
+┌─────────────┐         ┌──────────────────┐         ┌────────────────────┐
+│     EOA     │  signs  │  SimpleAccount   │  calls  │ ContractDeployer   │
+│  (no gas)   ├────────>│  (pays all gas)  ├────────>│  (uses CREATE)     │
+└─────────────┘         └──────────────────┘         └────────┬───────────┘
+                                                               │ deploys
+                                                               v
+                                                       ┌────────────────────┐
+                                                       │   KAMI Contract    │
+                                                       │   (your NFT)       │
+                                                       └────────────────────┘
+```
 
-#### ❌ "Contract already exists"
+### Why ContractDeployer?
 
--   **Solution**: Use a different salt or check if contract is already deployed
+SimpleAccount's `execute()` function **cannot deploy contracts** directly. Calling `execute(address(0), 0, bytecode)` doesn't use the CREATE opcode - it just calls the zero address which does nothing.
 
-#### ❌ "Owner verification failed"
+ContractDeployer solves this by:
 
--   **Solution**: Ensure the NFT contract has an `owner()` function
+1. SimpleAccount calls `ContractDeployer.deploy(bytecode)`
+2. ContractDeployer uses CREATE opcode internally
+3. New contract is deployed with SimpleAccount as deployer
+4. Contract appears on block explorer correctly
 
-### Debug Steps
+This is a **one-time infrastructure cost** (~0.001 ETH) that enables unlimited gasless deployments.
 
-1. Check SimpleAccount balance: `fund-simpleaccount.ts check`
-2. Verify contract deployment: Check transaction on block explorer
-3. Test with small amounts first
-4. Check network connectivity and RPC endpoint
+## Migration from Old Version
 
-## 🌐 Supported Networks
+If you were using `KamiSimpleAccountDeployer`, it **doesn't work** and has been deprecated.
 
--   **Base Sepolia** (Testnet) - Recommended for testing
--   **Base Mainnet** - Production ready
--   **Ethereum Sepolia** - Testing
--   **Any EVM-compatible network** - With proper configuration
+See [MIGRATION_GUIDE.md](MIGRATION_GUIDE.md) for migration instructions.
 
-## 📚 Documentation
+## Additional Documentation
 
-### KAMI NFT Documentation
+-   [ALL_CONTRACT_TYPES.md](ALL_CONTRACT_TYPES.md) - Detailed comparison of all contract types
+-   [MIGRATION_GUIDE.md](MIGRATION_GUIDE.md) - Migration from deprecated classes
+-   [UPDATED_SOLUTION.md](UPDATED_SOLUTION.md) - Technical details and rationale
+-   [docs/GASLESS_DEPLOYMENT_FIX.md](docs/GASLESS_DEPLOYMENT_FIX.md) - Deep dive into the solution
 
--   🔴 **[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!**
--   ⚡ **[Gasless Payment Flow](./docs/KAMI_PAYMENT_GASLESS_FLOW.md)** - Truly gasless payment setup
--   💰 **[Payment Flow Guide](./docs/KAMI_PAYMENT_FLOW.md)** - ERC20 payment token setup
--   📝 **[Payment Quick Reference](./docs/KAMI_PAYMENT_SUMMARY.md)** - Quick payment setup guide
--   📊 **[Gas Savings Analysis](./docs/KAMI_GAS_SAVINGS_ANALYSIS.md)** - Detailed cost breakdown (saves 44-66%!)
--   📘 **[KAMI Operations Guide](./docs/KAMI_OPERATIONS.md)** - Complete operations reference (UPDATED v0.4.0)
--   📚 **[Library Sharing Guide](./docs/KAMI_LIBRARY_SHARING.md)** - Maximize efficiency
--   🔍 **[Library Verification Guide](./docs/LIBRARY_VERIFICATION_GUIDE.md)** - Check if libraries are deployed
--   🆕 **[Next.js Library Deployment](./docs/NEXTJS_LIBRARY_DEPLOYMENT.md)** - **Using libraries in Next.js APIs**
--   🚀 **[Quick Start](./docs/KAMI_QUICK_START.md)** - Get started in 5 minutes
--   🔧 **[Deployment Notes](./docs/KAMI_DEPLOYMENT_NOTES.md)** - Production considerations
--   💡 **[Mint with TokenId Example](./examples/mint-with-tokenid-example.ts)** - Get token info from mints
--   💡 **[Payment Example](./examples/kami-payment-example.ts)** - Complete payment flow example
--   💡 **[Library Sharing Example](./examples/deploy-shared-libraries-example.ts)** - Shared libraries
+## Contributing
 
-### General Documentation
+Contributions welcome! Please open an issue or PR.
 
--   [Gas Optimization Guide](./docs/GAS_OPTIMIZATION_GUIDE.md)
--   [SimpleAccount Owner Deployment](./docs/SIMPLEACCOUNT_OWNER_DEPLOYMENT.md)
--   [NFT Listing Guide](./docs/NFT_LISTING_GUIDE.md)
--   [Library Overview](./docs/LIBRARY_OVERVIEW.md)
--   [Complete Workflow Guide](./docs/COMPLETE_WORKFLOW_PAULSNFT.md)
+## License
 
----
+[Your License Here]
 
-## 📄 License
+## Support
 
-MIT License - see [LICENSE](LICENSE) file for details.
+For issues, questions, or feature requests, please open a GitHub issue.
 
-## 🤝 Contributing
+## Summary
 
-Contributions are welcome! Please read our contributing guidelines and submit pull requests to our GitHub repository.
+This library provides a **complete solution** for deploying KAMI NFT contracts with true gasless transactions:
 
-## 📞 Support
+-   ✅ **Complete setup guide** - From zero to deployed NFT contract
+-   ✅ **Three contract types** - KAMI721C, KAMI721AC, KAMI1155C
+-   ✅ **Truly gasless** - SimpleAccount pays all gas
+-   ✅ **Production ready** - Battle-tested and documented
+-   ✅ **Type-safe** - Full TypeScript support
+-   ✅ **Creator features** - Royalties, rentals, platform fees built-in
 
--   **Documentation**: Check the `docs/` folder for detailed guides
--   **Issues**: Report bugs and request features on GitHub
--   **Discussions**: Join our community discussions
+**Get started in minutes. Deploy NFTs gaslessly in production.** 🚀