@paulstinchcombe/gasless-nft-tx 0.7.2 → 0.8.1

package/README.md

@@ -1,779 +1,335 @@
-# Gasless NFT Transactions Library
+# Sponsored KAMI NFT Transactions Library
 
-A comprehensive TypeScript library for deploying and managing KAMI NFT contracts with truly gasless transactions using EIP-4337 Account Abstraction and SimpleAccount.
-
-> **📚 For the complete consolidated guide, see [docs/CONSOLIDATED_GUIDE.md](docs/CONSOLIDATED_GUIDE.md)**
+A comprehensive TypeScript library for **truly sponsored** KAMI NFT operations where users pay **ZERO gas fees** for all transactions.
 
 ## 🎯 What This Library Does
 
--   ✅ **Truly Gasless Deployments** - Deploy NFT contracts where SimpleAccount pays all gas
+-   ✅ **Truly Sponsored Operations** - Users pay ZERO gas fees for ALL operations
+-   ✅ **Complete NFT Management** - Deploy, mint, rent, sell, and manage NFTs
 -   ✅ **Three NFT Standards** - Support for KAMI721C (ERC721), KAMI721AC (ERC721A), and KAMI1155C (ERC1155)
--   ✅ **Consistent API** - All three handlers share the same method signatures (v0.5.3+)
--   ✅ **Creator Features** - Built-in royalties, rentals, and platform fees
--   ✅ **Library Linking** - Automatic handling of Solidity library dependencies
+-   ✅ **Platform-Sponsored** - Platform pays all gas costs
+-   ✅ **User Ownership** - All contracts owned by user's EOA
 -   ✅ **Type-Safe** - Full TypeScript support with comprehensive type definitions
 
-## 📋 Table of Contents
-
--   [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)
--   [Gasless Paid Minting](#gasless-paid-minting)
--   [SimpleAccount Strategy](#simpleaccount-strategy)
--   [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);
+## 🏗️ Architecture
 
-// 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"
+┌─────────────────┐    Signs Message    ┌──────────────────┐    Pays All Gas    ┌────────────────────┐
+│   User's EOA    ├───────────────────>│  Platform        ├───────────────────>│   KAMI Contract    │
+│  (NO ETH)       │                    │  SimpleAccount   │                    │   (executes)       │
+└─────────────────┘                    └──────────────────┘                    └────────────────────┘
 ```
 
-#### Funding SimpleAccount
+## 🚀 Quick Start
 
-SimpleAccount needs ETH to pay for gas:
+### 1. Installation
 
 ```bash
-# 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
+npm install @paulstinchcombe/gasless-nft-tx
 ```
 
-**Update `.env`:**
+### 2. Deploy Infrastructure (One-Time Setup)
 
 ```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
-
-   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!
-```
-
-**Cost:** ~0.001 ETH from your EOA (one-time only)
-
-**Update `.env`:**
-
-```bash
-CONTRACT_DEPLOYER_ADDRESS="0x..."
-```
-
-### Step 4: Deploy KAMI Libraries
-
-KAMI contracts use five shared libraries. Deploy them once and reuse for all NFT contracts.
-
-```bash
-npx tsx examples/deploy-shared-libraries-example.ts
-```
-
-**Expected Output:**
-
-```
-📚 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
-```
-
-**Expected Output:**
-
-```
-🚀 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...
-```
-
-**Cost:** ~0.015 ETH from SimpleAccount (per deployment)
-
-**Save the contract address:**
+# Set your platform private key
+export PRIVATE_KEY="0x..."
 
-```bash
-export KAMI721C_ADDRESS="0x..."
+# Deploy all infrastructure needed for sponsored transactions
+npx tsx setup-sponsored-infrastructure.ts
 ```
 
-## Contract Types
-
-### KAMI721C - Standard ERC721 with Creator Features
-
-**Use for:**
-
--   Standard NFT collections
--   Art projects
--   Collectibles
--   Small to medium collections (< 1,000 NFTs)
-
-**Features:**
+This will deploy:
 
--   ✅ ERC721 standard compliance
--   ✅ Creator royalties (EIP-2981)
--   ✅ Rental system
--   ✅ Platform fees
--   ✅ Maximum compatibility
+-   SimpleAccountFactory
+-   Platform SimpleAccount (funded with ETH)
+-   ContractDeployer helper
+-   KAMI Libraries
 
-**Deployment:**
+### 3. Platform Setup
 
 ```typescript
-import { KamiGaslessDeployerWithLibraries, KAMI721CParams } from 'your-package-name';
-import { parseEther, Address } from 'viem';
+import { KamiSponsoredOperations, KamiSponsoredDeployment } from '@paulstinchcombe/gasless-nft-tx';
 
-const deployer = new KamiGaslessDeployerWithLibraries({
+// Platform configuration
+const config = {
 	rpcUrl: 'https://sepolia.base.org',
-	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,
-	},
-});
-
-const params: KAMI721CParams = {
-	paymentToken: '0x0000000000000000000000000000000000000000', // Native ETH
-	name: 'My NFT Collection',
-	symbol: 'MNFT',
-	baseTokenURI: 'ipfs://QmYourBaseURI/',
-	platformAddress: process.env.SIMPLE_ACCOUNT_ADDRESS as Address,
-	platformCommissionPercentage: 250, // 2.5%
-	adminAddress: process.env.SIMPLE_ACCOUNT_ADDRESS as Address, // Admin address
-};
-
-const result = await deployer.deployKAMI721C(params);
-console.log('Deployed at:', result.contractAddress);
-```
-
-### 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/',
-	platformAddress: process.env.SIMPLE_ACCOUNT_ADDRESS as Address,
-	platformCommissionPercentage: 250,
-	adminAddress: process.env.SIMPLE_ACCOUNT_ADDRESS as Address,
+	platformPrivateKey: process.env.PLATFORM_PRIVATE_KEY, // Platform's key (has ETH)
+	platformSimpleAccountAddress: process.env.PLATFORM_SIMPLE_ACCOUNT_ADDRESS, // Platform's SA (has ETH)
+	contractDeployerAddress: process.env.CONTRACT_DEPLOYER_ADDRESS,
+	platformAddress: process.env.PLATFORM_ADDRESS,
+	paymentToken: process.env.PAYMENT_TOKEN,
 };
 
-const result = await deployer.deployKAMI721AC(params);
+// Create handlers
+const sponsoredDeployment = new KamiSponsoredDeployment(config);
+const sponsoredOps = new KamiSponsoredOperations(config);
 ```
 
-**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:**
+### 4. Deploy Contract (Sponsored)
 
 ```typescript
-const params: KAMI1155CParams = {
-	paymentToken: '0x0000000000000000000000000000000000000000',
-	baseTokenURI: 'ipfs://QmYourBaseURI/{id}.json', // {id} auto-replaced
-	platformAddress: process.env.SIMPLE_ACCOUNT_ADDRESS as Address,
+// User signs message for deployment (no ETH needed)
+const userSignature = createUserSignatureData(
+	userAddress,
+	"Paul's NFT Collection",
+	'PNC',
+	'https://api.example.com/metadata/',
+	parseEther('0.001'),
+	250, // 2.5% platform commission
+	userSignature
+);
+
+// Platform deploys contract with sponsored gas
+const result = await sponsoredDeployment.deployKAMI721C({
+	contractName: "Paul's NFT Collection",
+	contractSymbol: 'PNC',
+	baseTokenURI: 'https://api.example.com/metadata/',
+	initialMintPrice: parseEther('0.001'),
 	platformCommissionPercentage: 250,
-	adminAddress: process.env.SIMPLE_ACCOUNT_ADDRESS as Address,
-};
+	userSignature,
+});
 
-const result = await deployer.deployKAMI1155C(params);
+console.log('Contract deployed:', result.contractAddress);
+console.log('Gas paid by: Platform');
+console.log('User paid: ZERO ETH');
 ```
 
-## API Reference
-
-### KamiGaslessDeployerWithLibraries
-
-Main class for deploying KAMI contracts gaslessly.
-
-#### Constructor
+### 5. Mint Token (Sponsored)
 
 ```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
+// User signs message for minting (no ETH needed)
+const mintSignature = createSponsoredOperationSignature(
+	userAddress,
+	'mint',
+	contractAddress,
+	{
+		recipient: userAddress,
+		tokenPrice: parseEther('0.001'),
+		uri: 'https://api.example.com/metadata/1',
+		mintRoyalties: [
+			{ receiver: userAddress, percentage: 500 },
+			{ receiver: platformAddress, percentage: 250 },
+		],
+	},
+	userSignature
+);
+
+// Platform mints token with sponsored gas
+const result = await sponsoredOps.mintToken(
+	contractAddress,
+	'KAMI721C',
+	{
+		recipient: userAddress,
+		tokenPrice: parseEther('0.001'),
+		uri: 'https://api.example.com/metadata/1',
+		mintRoyalties: [
+			{ receiver: userAddress, percentage: 500 },
+			{ receiver: platformAddress, percentage: 250 },
+		],
+	},
+	mintSignature
+);
 
-```typescript
-async deployKAMI721C(params: KAMI721CParams): Promise<DeploymentResult>
+console.log('Token minted:', result.data?.tokenId);
+console.log('Gas paid by: Platform');
+console.log('User paid: ZERO ETH');
 ```
 
-Deploy a KAMI721C contract (ERC721 + Creator).
+## 📋 Supported Operations
 
-**Parameters:**
+### **Deployment Operations**
 
--   `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
--   `platformAddress` (Address): Platform fee recipient
--   `platformCommissionPercentage` (number): Platform fee (250 = 2.5%)
--   `adminAddress` (Address): Admin address for contract management
+-   ✅ **Deploy KAMI721C** - ERC721 with Creator features
+-   ✅ **Deploy KAMI721AC** - ERC721A with batch minting
+-   ✅ **Deploy KAMI1155C** - ERC1155 multi-token
 
-**Returns:**
+### **Minting Operations**
 
-```typescript
-{
-  success: boolean;
-  contractAddress?: Address;
-  transactionHash?: string;
-  error?: string;
-}
-```
+-   ✅ **Mint tokens** with custom prices and royalties
+-   ✅ **Batch minting** for KAMI721AC
+-   ✅ **Multi-token minting** for KAMI1155C
 
-##### deployKAMI721AC
+### **Rental Operations**
 
-```typescript
-async deployKAMI721AC(params: KAMI721ACParams): Promise<DeploymentResult>
-```
+-   ✅ **Rent tokens** for specific durations
+-   ✅ **Extend rentals** with additional payment
+-   ✅ **End rentals** when duration expires
 
-Deploy a KAMI721AC contract (ERC721A + Creator).
+### **Sales Operations**
 
-Same parameters as KAMI721C.
+-   ✅ **Sell tokens** to other users
+-   ✅ **Transfer ownership** with payment
 
-##### deployKAMI1155C
+### **Management Operations**
 
-```typescript
-async deployKAMI1155C(params: KAMI1155CParams): Promise<DeploymentResult>
-```
+-   ✅ **Set token prices** individually
+-   ✅ **Set token URIs** for metadata
+-   ✅ **Set token royalties** and recipients
+-   ✅ **Contract administration** (pause/unpause)
 
-Deploy a KAMI1155C contract (ERC1155 + Creator).
+## 💰 Cost Analysis
 
-**Parameters:**
+### **User Costs**
 
--   `paymentToken` (Address): Payment token address
--   `baseTokenURI` (string): Base URI with {id} placeholder
--   `platformAddress` (Address): Platform fee recipient
--   `platformCommissionPercentage` (number): Platform fee percentage
--   `adminAddress` (Address): Admin address for contract management
+-   **Gas Fees**: **ZERO ETH** ✅
+-   **Transaction Fees**: **ZERO ETH** ✅
+-   **All Operations**: **ZERO ETH** ✅
 
-##### getBalance
+### **Platform Costs**
 
-```typescript
-async getBalance(): Promise<bigint>
-```
+-   **Contract Deployment**: ~0.015 ETH per contract
+-   **Token Minting**: ~0.003 ETH per token
+-   **Other Operations**: ~0.001-0.002 ETH per operation
 
-Get SimpleAccount's current ETH balance.
+## 🔧 Environment Setup
 
-### Type Definitions
+Create a `.env` file:
 
-```typescript
-// Library addresses (shared by all contracts)
-interface LibraryAddresses {
-	kamiNFTCore: Address;
-	kamiPlatform: Address;
-	kamiRoyalty: Address;
-	kamiRental: Address;
-	kamiTransfer: Address;
-}
-
-// Deployment result
-interface DeploymentResult {
-	success: boolean;
-	contractAddress?: Address;
-	transactionHash?: string;
-	error?: string;
-}
+```bash
+# Platform Configuration
+PLATFORM_PRIVATE_KEY="0x..." # Platform's private key (has ETH)
+PLATFORM_SIMPLE_ACCOUNT_ADDRESS="0x..." # Platform's SimpleAccount (has ETH)
+CONTRACT_DEPLOYER_ADDRESS="0x..." # ContractDeployer address
+PLATFORM_ADDRESS="0x..." # Platform address
+PAYMENT_TOKEN="0x..." # Payment token address (USDC, etc.)
+
+# Network Configuration
+RPC_URL="https://sepolia.base.org"
 ```
 
-## Gas Costs
-
-All costs are estimates on Base Sepolia. Mainnet costs may vary.
-
-### One-Time Setup Costs
-
-| 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     |
-
-**Total Setup**: ~0.014 ETH (one-time)
-
-### Per-Deployment Costs
-
-| 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         |
-
-**After Setup**: Deploy unlimited contracts for ~0.015 ETH each (from SimpleAccount)
-
-### Gasless Benefits
-
--   ✅ **Users pay nothing** - All gas paid by SimpleAccount
--   ✅ **EOA only signs** - No ETH needed in user wallet
--   ✅ **True gasless experience** - Best UX possible
+## 📚 Documentation
 
-## Examples
+-   [Sponsored Deployment Guide](docs/SPONSORED_DEPLOYMENT_GUIDE.md) - Complete deployment guide
+-   [Sponsored Operations Guide](docs/SPONSORED_OPERATIONS_GUIDE.md) - Complete operations guide
+-   [Migration Guide](docs/MIGRATION_GUIDE.md) - Migrate from old gasless to sponsored
+-   [Examples](examples/README.md) - Working examples and frontend integration
 
-All examples are in the `examples/` directory:
+## 🚀 Examples
 
 ### Infrastructure Setup
 
--   `gasless-deployment-complete.ts` - Deploy ContractDeployer
--   `deploy-shared-libraries-example.ts` - Deploy KAMI libraries
--   `check-library-deployment.ts` - Verify library deployments
-
-### Contract Deployment
-
--   `true-gasless-deployment.ts` - Deploy KAMI721C
--   `deploy-kami721ac-gasless.ts` - Deploy KAMI721AC
--   `deploy-kami1155c-gasless.ts` - Deploy KAMI1155C
-
-### SimpleAccount Setup
-
--   `deploy-simple-deployer.ts` - Deploy SimpleAccountFactory
--   `fund-simpleaccount.ts` - Fund SimpleAccount with ETH
-
-## Gasless Paid Minting
-
-**Important**: For mints with ERC20 payment tokens, the library handles ALL approvals gaslessly!
-
-👉 **[Gasless Paid Minting Guide](docs/GASLESS_PAID_MINTING.md)**
-
-**Quick Summary:**
-
--   ✅ User has payment tokens (USDC, etc.) but NO ETH
--   ✅ Library handles ERC20 approval gaslessly via SimpleAccount
--   ✅ Library automatically checks transaction status
--   ✅ Complete workflow with code examples
--   ❌ Don't forget to check payment status and approve before minting!
-
-See the guide for complete workflow, API examples, and common mistakes to avoid.
-
-## SimpleAccount Strategy
-
-**Important**: You only need **ONE SimpleAccount for your entire platform**, not one per user!
-
-👉 **[SimpleAccount Strategy Guide](docs/SIMPLEACCOUNT_STRATEGY.md)**
-
-**Quick Summary:**
-
--   ✅ Use 1 SimpleAccount for your platform (saves $50+ on 100 users)
--   ✅ Deploy NFT contracts for all users through it
--   ✅ Users control their NFTs with their existing wallets
--   ❌ Don't create SimpleAccount per user (unnecessary and expensive)
-
-See the guide for cost analysis, implementation examples, and when users would need their own SimpleAccount.
-
-## KAMI Handler APIs
-
-**Important**: All three KAMI handlers now have consistent APIs! (v0.7.0+)
-
-👉 **[KAMI721AC Handler API Reference](docs/KAMI721AC_HANDLER_API.md)**
-
-**What Changed in v0.7.0:**
-
--   ✅ **New Constructor Parameters**: All contracts now require `adminAddress` parameter
--   ✅ **Removed `initialMintPrice`**: Price is now set per-token during minting
--   ✅ **New Methods Added**: `setMintRoyalties`, `setTransferRoyalties`, `setPlatformCommission`, `hasClaimed`, `hasActiveRentals`
--   ✅ **Enhanced Royalty Management**: Token-specific and global royalty controls
--   ✅ **Platform Commission Management**: Dynamic platform fee updates
--   ✅ **Claim Tracking**: Built-in claim status tracking for KAMI721AC
-
-**What Changed in v0.5.3:**
-
--   ✅ `KAMI721ACSimpleAccountHandler` now matches `KAMI721CSimpleAccountHandler` API
--   ✅ `mint()` now requires `recipient`, `tokenPrice`, and `uri` parameters
--   ✅ Added missing methods: `setPrice()`, `setTokenURI()`
--   ✅ Batch methods now require `prices` and `uris` arrays
-
-**Migration Examples:**
-
-```typescript
-// ❌ OLD Constructor (v0.6.x)
-const params = {
-	paymentToken: '0x...',
-	name: 'My NFT',
-	symbol: 'NFT',
-	baseTokenURI: 'ipfs://...',
-	initialMintPrice: parseEther('0.001'), // ❌ Removed
-	platformAddress: '0x...',
-	platformCommissionPercentage: 250,
-};
-
-// ✅ NEW Constructor (v0.7.0+)
-const params = {
-	paymentToken: '0x...',
-	name: 'My NFT',
-	symbol: 'NFT',
-	baseTokenURI: 'ipfs://...',
-	platformAddress: '0x...',
-	platformCommissionPercentage: 250,
-	adminAddress: '0x...', // ✅ Required
-};
-
-// ❌ OLD Mint (v0.5.2)
-await handler.mint(recipientAddress);
+```bash
+# Deploy all infrastructure (one-time setup)
+npx tsx setup-sponsored-infrastructure.ts
 
-// ✅ NEW Mint (v0.7.0+)
-await handler.mint(recipientAddress, tokenPrice, tokenURI, mintRoyalties);
+# Deploy individual components
+npx tsx deploy-simpleaccount.ts
+npx tsx deploy-contract-deployer.ts
+npx tsx deploy-kami-libraries.ts
 ```
 
-See the guide for complete API reference, migration instructions, and examples.
-
-## Next.js Deployment
-
-If you're using this library in a Next.js API route, you'll encounter artifact loading issues. See the complete guide:
-
-👉 **[Next.js Deployment Guide](docs/NEXTJS_DEPLOYMENT.md)**
-
-**Quick Summary**: The library loads contract artifacts using `fs.readFileSync()`, which doesn't work in Next.js production builds. You need to:
-
-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
-
-The guide includes complete code examples and troubleshooting steps.
-
-## Troubleshooting
-
-### Next.js "ENOENT: no such file or directory" Error
-
-**Symptoms**: Error opening KAMI721C.json artifact file in production
-
-**Solution**: See [Next.js Deployment Guide](docs/NEXTJS_DEPLOYMENT.md) for complete fix with ready-to-use wrapper class.
-
-**Quick Fix**: Use the `NextJsKamiDeployer` wrapper that imports artifacts directly instead of loading from disk.
-
-### Contract Not Appearing on BaseScan
-
-**Wait 1-2 minutes** for block explorer indexing.
-
-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
+### Backend Examples
 
 ```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
-```
+# Deploy contracts with sponsored gas
+npx tsx examples/sponsored-deployment-example.ts
 
-### "ContractDeployer not deployed" Error
-
-Deploy ContractDeployer first:
-
-```bash
-npx tsx examples/gasless-deployment-complete.ts
+# Perform all operations with sponsored gas
+npx tsx examples/sponsored-operations-example.ts
 ```
 
-### "Library addresses invalid" Error
+### Frontend Examples
 
-Verify all libraries are deployed:
-
-```bash
-npx tsx examples/check-library-deployment.ts
+```typescript
+// User signs message for any operation
+const { userAddress, signature, nonce } = await requestUserSignatureForOperation(
+	'mint',
+	contractAddress,
+	{
+		recipient: userAddress,
+		tokenPrice: parseEther('0.001'),
+		uri: 'https://api.example.com/metadata/1',
+		mintRoyalties: [
+			{ receiver: userAddress, percentage: 500 },
+			{ receiver: platformAddress, percentage: 250 },
+		],
+	},
+	userAddress
+);
 ```
 
-### 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
-
-This usually means:
+## 🛡️ Security
 
--   Bytecode has formatting issues (spaces in hex)
--   Update to latest version of the library
+-   **Signature Verification**: All user signatures are verified
+-   **Replay Protection**: Nonce and timestamp prevent replay attacks
+-   **Parameter Validation**: All operation parameters are validated
+-   **Platform Security**: Platform private keys are kept secure
 
-### "Nonce too low" Error in Sequential Transactions
+## 🎯 Benefits
 
-**Symptoms**: Getting "nonce too low" error when minting after approval
+1. **True Gasless Experience**: Users never need ETH
+2. **Complete Operation Coverage**: All KAMI functions supported
+3. **Platform Control**: Platform manages all gas costs
+4. **User Ownership**: Operations affect user's contracts
+5. **Scalable**: One platform SimpleAccount serves all users
+6. **Cost Effective**: Platform pays only for actual operations
 
-**Fixed in v0.5.2**: The library now explicitly manages nonces to prevent race conditions.
+## 🔧 API Reference
 
-If you're still experiencing this:
+### Sponsored Deployment
 
-1. **Update to v0.5.2 or later**: `npm install @paulstinchcombe/gasless-nft-tx@latest`
-2. **Check you're not manually managing nonces**: Let the library handle it
-3. **See detailed explanation**: [docs/NONCE_COLLISION_FIX.md](docs/NONCE_COLLISION_FIX.md)
-
-The fix ensures that when approval and mint transactions happen in quick succession, each transaction gets the correct nonce using `blockTag: 'pending'`.
-
-## Architecture
+```typescript
+// Deploy KAMI721C
+const result = await sponsoredDeployment.deployKAMI721C(params);
 
-### How It Works
+// Deploy KAMI721AC
+const result = await sponsoredDeployment.deployKAMI721AC(params);
 
-```
-┌─────────────┐         ┌──────────────────┐         ┌────────────────────┐
-│     EOA     │  signs  │  SimpleAccount   │  calls  │ ContractDeployer   │
-│  (no gas)   ├────────>│  (pays all gas)  ├────────>│  (uses CREATE)     │
-└─────────────┘         └──────────────────┘         └────────┬───────────┘
-                                                               │ deploys
-                                                               v
-                                                       ┌────────────────────┐
-                                                       │   KAMI Contract    │
-                                                       │   (your NFT)       │
-                                                       └────────────────────┘
+// Deploy KAMI1155C
+const result = await sponsoredDeployment.deployKAMI1155C(params);
 ```
 
-### Why ContractDeployer?
+### Sponsored Operations
 
-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.
+```typescript
+// Mint token
+const result = await sponsoredOps.mintToken(contractAddress, contractType, params, signature);
 
-ContractDeployer solves this by:
+// Rent token
+const result = await sponsoredOps.rentToken(contractAddress, contractType, params, signature);
 
-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
+// Sell token
+const result = await sponsoredOps.sellToken(contractAddress, contractType, params, signature);
 
-This is a **one-time infrastructure cost** (~0.001 ETH) that enables unlimited gasless deployments.
+// Set price
+const result = await sponsoredOps.setPrice(contractAddress, contractType, params, signature);
 
-## Migration from Old Version
+// Set URI
+const result = await sponsoredOps.setTokenURI(contractAddress, contractType, params, signature);
 
-If you were using `KamiSimpleAccountDeployer`, it **doesn't work** and has been deprecated.
+// Set royalties
+const result = await sponsoredOps.setTokenRoyalties(contractAddress, contractType, params, signature);
 
-See [MIGRATION_GUIDE.md](MIGRATION_GUIDE.md) for migration instructions.
+// Pause contract
+const result = await sponsoredOps.pauseContract(contractAddress, contractType, signature);
 
-## Additional Documentation
+// Unpause contract
+const result = await sponsoredOps.unpauseContract(contractAddress, contractType, signature);
+```
 
--   [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
+## 🚀 Getting Started
 
-## Contributing
+1. **Install the library**: `npm install @paulstinchcombe/gasless-nft-tx`
+2. **Set up environment**: Create `.env` file with platform configuration
+3. **Deploy infrastructure**: Deploy ContractDeployer and libraries (one-time setup)
+4. **Start using**: Deploy contracts and perform operations with sponsored gas!
 
-Contributions welcome! Please open an issue or PR.
+## 📄 License
 
-## License
+MIT License - see LICENSE file for details.
 
-[Your License Here]
+## 🤝 Contributing
 
-## Support
+Contributions are welcome! Please read our contributing guidelines and submit pull requests.
 
-For issues, questions, or feature requests, please open a GitHub issue.
+## 📞 Support
 
-## Summary
+For support and questions:
 
-This library provides a **complete solution** for deploying KAMI NFT contracts with true gasless transactions:
+-   Create an issue on GitHub
+-   Check the documentation
+-   Review the examples
 
--   ✅ **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
+---
 
-**Get started in minutes. Deploy NFTs gaslessly in production.** 🚀
+**🎉 Enjoy truly gasless NFT operations with the Sponsored KAMI NFT Transactions Library!**