KidLisp Keeps - NFT Minting System#

Overview#

"Keeps" are KidLisp pieces preserved as NFTs on Tezos. Each $code can only exist once at a time, ensuring uniqueness and provenance.

Current Contract (v3)#

Legacy (v2): KT1EcsqR69BHekYF5mDQquxrvNg5HhPFx6NM (archived, do not use for new mints)

Storage#

Entrypoints#

v3 Permission Model (edit_metadata)#

edit_metadata authorization (in order of check):
1. Admin — can edit any token
2. Owner — current holder of the token  
3. Creator — address stored in token_creators[token_id]

⚠️  For objkt.com artist attribution:
   The CREATOR must call edit_metadata, not admin!
   Admin calls show admin as "updater" on objkt.

Uniqueness Enforcement#

• Each piece name (e.g., "cow", "roz") can only be minted once
• content_hashes big_map tracks: piece_name → token_id
• Burning removes the entry, allowing re-mint
• Checked client-side via TzKT API before IPFS upload

CLI Commands (node keeps.mjs)#

Fee System#

The contract supports configurable mint fees. See KEEPS-FEE-SYSTEM.md for full documentation.

Quick Reference#

# Check current fee
node keeps.mjs fee

# Set fee to 5 XTZ
node keeps.mjs set-fee 5

# Withdraw accumulated fees
node keeps.mjs withdraw

Storage & Entrypoints#

• keep_fee (mutez) - Required payment to keep
• set_keep_fee(new_fee) - Admin updates fee
• withdraw_fees(destination) - Admin withdraws balance

⚠️ Note: Fee system requires contract v2.1+ (with fee entrypoints). Existing contracts need redeployment.

Metadata Structure#

Token Metadata (TZIP-21)#

{
  "name": "$cow",
  "description": "(wipe \"blue\")\n(ink \"yellow\")\n...\n\nby @jeffrey\nac25namuc",
  "artifactUri": "ipfs://Qm...",
  "displayUri": "ipfs://Qm...",
  "thumbnailUri": "ipfs://Qm... (animated WebP)",
  "symbol": "KEEP",
  "tags": ["$cow", "KidLisp", "Aesthetic.Computer", "interactive"],
  "attributes": [
    { "name": "Language", "value": "KidLisp" },
    { "name": "Code", "value": "$cow" },
    { "name": "Author", "value": "@jeffrey" },
    { "name": "User Code", "value": "ac25namuc" },
    { "name": "Lines of Code", "value": "3" },
    { "name": "Dependencies", "value": "2" },
    { "name": "Packed", "value": "2025.12.9" },
    { "name": "Interactive", "value": "Yes" },
    { "name": "Platform", "value": "Aesthetic Computer" }
  ]
}

Collection Metadata#

{
  "name": "KidLisp Keeps",
  "version": "2.0.0",
  "interfaces": ["TZIP-012", "TZIP-016", "TZIP-021"],
  "imageUri": "https://oven.aesthetic.computer/keeps/latest",
  "homepage": "https://aesthetic.computer"
}

Infrastructure#

Services#

Thumbnail Generation#

• Format: Animated WebP
• Size: 96x96 @ 2x density (192x192 actual)
• Duration: 8 seconds capture
• FPS: 10 capture → 20 playback
• Quality: 70

Phase 2: Creator Authorization (PLANNED)#

Problem#

Currently only admin can mint. We want:

1. Only handled users (with @handle) can mint
2. Users can only mint their own pieces (pieces they authored)
3. Minting should be self-service via web UI

Existing Infrastructure#

Authentication#

• Auth0 provides JWT tokens via /userinfo endpoint
• authorize() in backend/authorization.mjs validates tokens
• Returns { sub, email, email_verified, ... }

Piece Ownership (Already Tracked!)#

The kidlisp-codes MongoDB collection already stores:

{
  code: "cow",           // Piece name
  source: "(wipe...)",   // Source code
  hash: "...",           // SHA-256 of source
  user: "auth0|123...",  // Creator's Auth0 sub ID ✅
  when: Date,            // Created timestamp
}

Handle Resolution#

• handleFor(userId) in backend/authorization.mjs gets @handle from sub
• fetchAuthorInfo(userId) in bundle-html.js resolves handle + userCode

Architecture#

┌─────────────────┐     ┌──────────────────────────────┐     ┌─────────────────┐
│   AC Frontend   │────▶│  /api/kidlisp-keep           │────▶│  Tezos Contract │
│   (user clicks  │     │  (Netlify function)          │     │  (SmartPy FA2)  │
│    "Keep" btn)  │     │                              │     │                 │
└─────────────────┘     │  1. Validate JWT (Auth0)     │     └─────────────────┘
        │               │  2. Check user has @handle   │
        │ JWT Bearer    │  3. Verify piece ownership   │
        │ token         │  4. Check not already minted │
        ▼               │  5. Generate bundle & thumb  │
                        │  6. Upload to IPFS           │
                        │  7. Sign & submit Tezos tx   │
                        └──────────────────────────────┘
                                      │
                                      ▼
                        ┌──────────────────────────────┐
                        │  MongoDB `kidlisp-codes`     │
                        │  - code → user mapping       │
                        │  - piece ownership proof     │
                        └──────────────────────────────┘

Authorization Flow#

1. User Authentication (Auth0)

   const user = await authorize({ authorization: req.headers.authorization });
   if (!user) return 401 Unauthorized;
   

2. Handle Requirement

   const handle = await handleFor(user.sub);
   if (!handle) return 403 "You need an @handle to mint";
   

3. Piece Ownership Verification

   const piece = await db.collection('kidlisp-codes').findOne({ code: pieceName });
   if (!piece) return 404 "Piece not found";
   if (piece.user !== user.sub) return 403 "You don't own this piece";
   

4. Duplicate Check

   const duplicate = await checkDuplicatePiece(pieceName);
   if (duplicate.exists) return 409 "Already minted as token #X";
   

5. Minting

   • Generate bundle via existing bundle-html.js logic
   • Generate thumbnail via Oven
   • Upload to IPFS
   • Sign transaction with server-side admin key
   • Submit to Tezos

API Endpoints#

POST /api/kidlisp-keep#

Mint a new keep (requires auth)

Headers:

• Authorization: Bearer <JWT>

Body:

{
  "piece": "cow",
  "generateThumbnail": true
}

Response:

{
  "success": true,
  "tokenId": 5,
  "txHash": "op...",
  "artifactUri": "ipfs://...",
  "objktUrl": "https://objkt.com/asset/KT1.../5"
}

Errors:

• 401 - Not authenticated
• 403 - No @handle, or not piece owner
• 404 - Piece not found
• 409 - Already minted

GET /api/kidlisp-keep?piece=cow#

Check piece mint status (public)

Response:

{
  "piece": "cow",
  "canMint": true,
  "owner": "@jeffrey",
  "minted": false
}
// or if minted:
{
  "piece": "cow",
  "canMint": false,
  "minted": true,
  "tokenId": 5,
  "objktUrl": "https://..."
}

Security#

1. Admin Key Protection

   • Tezos private key in Netlify env: TEZOS_KIDLISP_KEY
   • Never exposed to client
   • Server signs all transactions

2. Ownership Enforcement

   • Only piece.user === user.sub can mint
   • First saver owns the piece (existing behavior)
   • Admin can mint any piece (bypass)

3. On-Chain Protection

   • SmartPy contract: assert self.is_administrator_() on all mutations
   • content_hashes big_map prevents duplicate minting
   • Metadata locking is permanent once applied

4. Rate Limiting (Future)

   • Per-user limits (e.g., 5 mints/day)
   • Prevent spam

Scalability (Designed for Millions of Pieces)#

1. Token ID Retrieval - O(1)

   • Uses next_token_id - 1 from storage, not pagination
   • Works at any scale

2. Duplicate Check - O(1)

   • content_hashes big_map lookup by key
   • Big maps are hash tables, constant-time access

3. Status Command - O(1) with pagination

   • Uses TzKT API with limit and sort.desc
   • Shows only recent tokens, total count from storage

4. Gas Costs - Constant

   • Big map operations don't increase with collection size
   • ~0.05 tez per mint regardless of token count

5. IPFS Storage

   • ~50KB per piece average (bundle + metadata + thumb)
   • 1M pieces ≈ 50GB = ~$7.50/month on Pinata

Implementation Steps#

1. Document existing infrastructure
2. Implement /api/kidlisp-keep GET (check status)
3. Implement /api/kidlisp-keep POST (mint)
4. Add "Keep" button to UI when viewing own piece
5. Test locally with dev server
6. Deploy to production
7. Add rate limiting

Environment Variables Needed#

# Netlify env vars (already have most of these)
TEZOS_KIDLISP_KEY=edsk...       # Admin signing key
TEZOS_CONTRACT_ADDRESS=KT1...   # Keeps contract
TEZOS_NETWORK=ghostnet          # or mainnet
PINATA_API_KEY=...              # For IPFS uploads
PINATA_API_SECRET=...
OVEN_URL=https://oven.aesthetic.computer

Files#

Deployment History#