mint-day 0.3.1 → 0.3.3

package/.env.example

@@ -0,0 +1,5 @@
+BASE_RPC_URL=
+MINT_FACTORY_ADDRESS=
+ANTHROPIC_API_KEY=
+CHAIN_ID=84532
+DEFAULT_RECIPIENT=

package/README.md

@@ -1,10 +1,58 @@
-# mint.day
+<div align="center">
+  <img src="site/assets/logo.png" alt="mint.day" width="80" />
+  <h1>mint.day</h1>
+  <p><strong>Free NFT minting for agents. On Base.</strong></p>
+  <p>Tell your agent what to mint. It lands on-chain in seconds.<br/>No wallet. No gas. No code.</p>
 
-Agents mint NFTs now.
+  [![npm](https://img.shields.io/npm/v/mint-day?color=2db87a&label=npm)](https://www.npmjs.com/package/mint-day)
+  [![license](https://img.shields.io/badge/license-MIT-2db87a)](LICENSE)
+  [![network](https://img.shields.io/badge/network-Base-0052FF)](https://basescan.org/address/0x12a1c11a0b2860f64e7d8df20989f97d40de7f2c)
+  [![live](https://img.shields.io/badge/live-mint.day-e5a030)](https://mint.day)
+</div>
 
-## Quick start
+---
 
-**1. Install** (zero config)
+<img src="site/assets/screenshot-home.png" alt="mint.day homepage" width="100%" />
+
+## What is mint.day?
+
+mint.day is an MCP server that gives any AI agent the ability to mint permanent, verifiable NFTs on Base. Identity cards, attestations, credentials, receipts, access passes — or any custom token you can describe in plain language.
+
+Gas is sponsored. Wallets are optional. It works whether you are a seasoned Solidity developer or someone who just discovered Claude Code last month.
+
+---
+
+## Get started in 60 seconds
+
+### Option A: You use Claude Code, Cursor, Windsurf, or any MCP client
+
+Copy this prompt and paste it into your AI assistant:
+
+```
+Install mint.day for me.
+
+mint.day is an MCP server that lets you mint NFTs on Base with natural language.
+Identity, attestations, credentials, receipts, access passes, and visual tokens with images.
+
+Add this MCP config:
+
+{
+  "mcpServers": {
+    "mint-day": {
+      "command": "npx",
+      "args": ["mint-day"]
+    }
+  }
+}
+
+That's it. No API keys. No wallet. Gas is sponsored. Just tell me what to mint.
+```
+
+Your assistant will handle the rest.
+
+### Option B: Add it manually
+
+Drop this into your MCP config file (`~/.cursor/mcp.json`, `claude_desktop_config.json`, etc.):
 
 ```json
 {
@@ -17,56 +65,77 @@ Agents mint NFTs now.
 }
 ```
 
-Works with Claude Code, Cursor, Windsurf, OpenClaw, and any MCP client.
+Restart your AI client. Done.
 
-**2. Mint**
+### Option C: npm package
 
-Tell your agent: "Proof I completed the security audit for 0xABC"
+```bash
+npm install mint-day
+```
 
-**3. Verify**
+```ts
+import { encodeMetadata } from 'mint-day';
 
-```
-mint_check({ address: "0xABC..." })
+const tokenURI = encodeMetadata({
+  name: "Audit complete: Protocol XYZ",
+  tokenType: "Attestation",
+  soulbound: true,
+  recipient: "0xABC..."
+});
 ```
 
-That's it. Your agent classifies the intent, builds the token, and returns a ready-to-sign transaction.
+---
 
-## Signing transactions
+## Try it now
 
-mint.day can sign and submit transactions directly, or return calldata for your own signer.
+Once installed, tell your agent anything like:
 
-### Option A: Built-in signing (recommended)
+> "Proof I shipped the v2 API today"
 
-Save a private key and mint.day handles everything:
+> "Mint me an identity token with my agent name and capabilities"
 
-```bash
-mkdir -p ~/.mint-day
-node -e "const w = require('ethers').Wallet.createRandom(); console.log(w.privateKey); console.error('Address: ' + w.address)"  2>&1 | head -1 > ~/.mint-day/credentials
-chmod 600 ~/.mint-day/credentials
-```
+> "Issue an access pass to 0xABC... for the beta"
 
-Fund the address with a small amount of ETH on Base (gas is < $0.01 per mint). Restart the MCP server.
+> "Receipt for 0.1 ETH paid to 0xDEF... on March 15"
 
-You can also set `PRIVATE_KEY` in your MCP env config instead of using the file.
+Your agent classifies the intent, builds the metadata, and returns a ready-to-sign transaction. Confirm, and it is on-chain.
 
-### Option B: Bring your own signer
+---
 
-Don't set a private key. mint.day returns calldata. Submit it with Coinbase AgentKit, Lit Protocol, Privy, or any EVM wallet.
+## Live feed
 
-## Tools
+<img src="site/assets/screenshot-feed.png" alt="mint.day live feed" width="100%" />
 
-### `mint`
+Browse all minted tokens at [mint.day/feed](https://mint.day/feed).
+
+---
+
+## Token types
+
+| Type | Default | Use for |
+|------|---------|---------|
+| **Identity** | transferable | Agent ID card, on-chain registration, DID |
+| **Attestation** | soulbound | Proof of action, task completion, audit trail |
+| **Credential** | soulbound | Reputation anchor, certification, earned status |
+| **Receipt** | transferable | Payment record, transaction proof between parties |
+| **Pass** | transferable | API access, capability unlock, membership |
+
+All types support `image` and `animation_url` for visual NFTs — PFPs, art, screenshots, generative visuals.
 
-Create a permanent, verifiable on-chain record on Base.
+---
 
-**Natural language:**
+## MCP tools
 
+### `mint`
+
+Create a permanent on-chain record.
+
+**Natural language** (agent classifies intent automatically):
 ```
 mint({ description: "Proof I completed the security audit for 0xABC" })
 ```
 
-**Structured** (skips classification):
-
+**Structured** (skip classification):
 ```
 mint({
   description: "Task completion attestation",
@@ -77,80 +146,105 @@ mint({
 ```
 
 **With an image:**
-
 ```
 mint({
   description: "My agent identity",
   tokenType: "Identity",
-  image: "data:image/png;base64,..."
+  image: "https://..." // or data:image/png;base64,...
 })
 ```
 
-Every mint returns a preview first. Confirm with `mintId` to execute:
+Every mint returns a **preview** first. Confirm with `mintId` to execute:
 
 ```
 mint({ mintId: "a3f8c1e90b2d" })
 ```
 
-With built-in signing, you get back a tx hash and explorer link. Without it, you get calldata.
+---
 
 ### `mint_check`
 
-Look up tokens by address, transaction hash, or get global stats.
+Look up tokens by address, tx hash, or get global stats.
 
 ```
-mint_check({ address: "0xABC..." })
-mint_check({ txHash: "0x230b..." })
-mint_check({})  // global stats
+mint_check({ address: "0xABC..." })    // all tokens for a wallet
+mint_check({ txHash: "0x230b..." })   // specific mint
+mint_check({})                         // global stats
 ```
 
+---
+
 ### `mint_resolve`
 
-Resolve an agent's on-chain identity. Returns their Identity token with ERC-8004 agent card metadata.
+Resolve an agent's on-chain identity. Returns their Identity token with ERC-8004 agent card metadata — DID, capabilities, endpoints.
 
 ```
 mint_resolve({ address: "0xABC..." })
 ```
 
-## Token types
+---
 
-| Type | Default | Use for |
-|------|---------|---------|
-| Identity | transferable | Agent ID card, on-chain registration |
-| Attestation | soulbound | Proof of action, task completion |
-| Credential | soulbound | Reputation anchor, certification |
-| Receipt | transferable | Payment record between two parties |
-| Pass | transferable | API access, capability unlock |
+## Signing transactions
+
+### Option A: Built-in signing (recommended)
+
+Generate a key, fund it with a small amount of ETH on Base (gas is less than $0.01), and mint.day handles signing and submission:
+
+```bash
+mkdir -p ~/.mint-day
+node -e "
+  const w = require('ethers').Wallet.createRandom();
+  console.log(w.privateKey);
+  console.error('Address: ' + w.address);
+" 2>&1 | head -1 > ~/.mint-day/credentials
+chmod 600 ~/.mint-day/credentials
+```
+
+Or set `PRIVATE_KEY` in your MCP env config.
 
-All types support `image` and `animation_url` for visual NFTs (PFPs, art, collectibles).
+### Option B: Bring your own signer
+
+No private key needed. mint.day returns calldata you can submit with Coinbase AgentKit, Privy, Lit Protocol, or any EVM wallet.
+
+---
 
-## Architecture
+## How it works
 
 ```
 Agent -> mint tool -> classifier (Groq Llama) -> metadata builder -> calldata
                                                                         |
-                         [if PRIVATE_KEY] sign + submit -> tx hash <----|
-                         [if no key]      return calldata <-------------|
+               [if PRIVATE_KEY] sign + submit -> tx hash, explorer link |
+               [if no key]      return calldata for your own signer -----|
                                                                         |
-                                                        MintFactory.sol (Base)
+                                               MintFactory.sol on Base mainnet
 ```
 
-## Contracts
-
-- **Base Mainnet**: [`0xbf12d372444dcf69df9316d961439f6b5919e8d0`](https://basescan.org/address/0xbf12d372444dcf69df9316d961439f6b5919e8d0)
-- **Base Sepolia**: [`0xa52450397f312c256Bd68B202C0CF90387Ea0E67`](https://sepolia.basescan.org/address/0xa52450397f312c256Bd68B202C0CF90387Ea0E67)
+---
 
 ## Configuration
 
 All optional. mint.day works with zero config.
 
-| Env var | Default | Purpose |
-|---------|---------|---------|
+| Variable | Default | Purpose |
+|----------|---------|---------|
 | `PRIVATE_KEY` | `~/.mint-day/credentials` | Signs and submits transactions |
 | `BASE_RPC_URL` | `https://mainnet.base.org` | RPC endpoint |
 | `CHAIN_ID` | `8453` | Base Mainnet |
-| `MINT_FACTORY_ADDRESS` | `0xbf12d3...` | Contract address |
-| `CLASSIFY_URL` | hosted endpoint | Intent classifier |
+| `MINT_FACTORY_ADDRESS` | see below | Override contract address |
+| `CLASSIFY_URL` | hosted endpoint | Intent classifier service |
+
+---
+
+## Contracts
+
+| Network | Address |
+|---------|---------|
+| **Base Mainnet** | [`0x12a1c11a0b2860f64e7d8df20989f97d40de7f2c`](https://basescan.org/address/0x12a1c11a0b2860f64e7d8df20989f97d40de7f2c) |
+| **Base Sepolia** | [`0x16e0072Eb4131106e266035E98Cfd07532B88EAa`](https://sepolia.basescan.org/address/0x16e0072Eb4131106e266035E98Cfd07532B88EAa) |
+
+Permissionless. Anyone can call `mint()` directly without the MCP server.
+
+---
 
 ## Development
 
@@ -161,6 +255,16 @@ npm run build   # compile to dist/
 npm start       # run compiled
 ```
 
-## License
+---
+
+## Links
+
+- [mint.day](https://mint.day) — live site
+- [mint.day/feed](https://mint.day/feed) — live feed of all minted tokens
+- [npm](https://www.npmjs.com/package/mint-day) — npm package
+- [OpenSea](https://opensea.io/collection/mintdotday) — collection
+- [X](https://x.com/mintdotday) — @mintdotday
+
+---
 
-MIT
+MIT — built by [@jordanlyall](https://x.com/jordanlyall)

package/api/classify.ts

@@ -0,0 +1,97 @@
+import type { VercelRequest, VercelResponse } from "@vercel/node";
+
+const GROQ_API_KEY = process.env.GROQ_API_KEY;
+const GROQ_MODEL = "llama-3.3-70b-versatile";
+const GROQ_URL = "https://api.groq.com/openai/v1/chat/completions";
+
+const SYSTEM_PROMPT = `You are a token type classifier for mint.day. Given a natural language minting request, return JSON with:
+- tokenType: one of "Identity", "Attestation", "Credential", "Receipt", "Pass"
+- soulbound: boolean
+- name: short descriptive name for the token
+- extractedFields: object with any additional fields you can extract (addresses, amounts, descriptions)
+- missingFields: array of field names that are required but not provided (empty if all present)
+
+Defaults:
+- Attestation and Credential are soulbound: true
+- Identity, Receipt, and Pass are soulbound: false
+- If the user explicitly says "soulbound" or "non-transferable", override the default
+- If the user explicitly says "transferable", set soulbound: false
+
+ERC-8004 Identity tokens REQUIRE these fields. Extract them if present, or add to missingFields:
+- did: decentralized identifier (e.g. "did:pkh:eip155:8453:0x...")
+- capabilities: array of strings describing what the agent can do
+- endpoints: array of strings with agent contact URIs (MCP, HTTP, etc.)
+
+Return ONLY valid JSON. No explanation.`;
+
+// Simple in-memory rate limiter: 60 requests per minute per IP
+const rateLimitMap = new Map<string, { count: number; resetAt: number }>();
+const RATE_LIMIT = 60;
+const RATE_WINDOW_MS = 60 * 1000;
+
+function checkRateLimit(ip: string): boolean {
+  const now = Date.now();
+  const entry = rateLimitMap.get(ip);
+  if (!entry || now > entry.resetAt) {
+    rateLimitMap.set(ip, { count: 1, resetAt: now + RATE_WINDOW_MS });
+    return true;
+  }
+  if (entry.count >= RATE_LIMIT) return false;
+  entry.count++;
+  return true;
+}
+
+export default async function handler(req: VercelRequest, res: VercelResponse) {
+  if (req.method !== "POST") {
+    return res.status(405).json({ error: "POST only" });
+  }
+
+  const ip = (req.headers["x-forwarded-for"] as string) || (req.headers["x-real-ip"] as string) || "unknown";
+  if (!checkRateLimit(ip)) {
+    return res.status(429).json({ error: "Rate limited. Try again in a minute." });
+  }
+
+  if (!GROQ_API_KEY) {
+    return res.status(500).json({ error: "Server misconfigured" });
+  }
+
+  const { text } = req.body || {};
+  if (!text || typeof text !== "string" || text.length > 1000) {
+    return res.status(400).json({ error: "text field required (max 1000 chars)" });
+  }
+
+  try {
+    const response = await fetch(GROQ_URL, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "Authorization": `Bearer ${GROQ_API_KEY}`,
+      },
+      body: JSON.stringify({
+        model: GROQ_MODEL,
+        messages: [
+          { role: "system", content: SYSTEM_PROMPT },
+          { role: "user", content: `Mint request: "${text}"` },
+        ],
+        max_tokens: 200,
+        temperature: 0,
+      }),
+    });
+
+    if (!response.ok) {
+      return res.status(502).json({ error: "Classification failed" });
+    }
+
+    const data = await response.json() as { choices: Array<{ message: { content: string } }> };
+    let content = data.choices[0].message.content;
+
+    // Strip markdown code fences if present
+    content = content.replace(/^```(?:json)?\s*\n?/i, "").replace(/\n?```\s*$/i, "").trim();
+
+    // Validate it's valid JSON before passing through
+    const parsed = JSON.parse(content);
+    return res.status(200).json(parsed);
+  } catch (err) {
+    return res.status(500).json({ error: "Classification failed", detail: String(err) });
+  }
+}

package/api/feed.ts

@@ -0,0 +1,71 @@
+import type { VercelRequest, VercelResponse } from "@vercel/node";
+import { ethers } from "ethers";
+
+const RPC_URL = process.env.BASE_RPC_URL || "https://base-mainnet.public.blastapi.io";
+const CONTRACT = process.env.MINT_FACTORY_ADDRESS || "0x12a1c11a0b2860f64e7d8df20989f97d40de7f2c";
+const DEPLOY_BLOCK = 43461700;
+const CHUNK_SIZE = 9999;
+
+const TOKEN_TYPES = ["Identity", "Attestation", "Credential", "Receipt", "Pass"];
+
+const ABI = [
+  "event Minted(uint256 indexed tokenId, address indexed to, uint8 tokenType, bool soulbound, string tokenURI)",
+];
+
+export default async function handler(req: VercelRequest, res: VercelResponse) {
+  res.setHeader("Access-Control-Allow-Origin", "*");
+  res.setHeader("Cache-Control", "s-maxage=30, stale-while-revalidate=60");
+
+  try {
+    const provider = new ethers.JsonRpcProvider(RPC_URL);
+    const contract = new ethers.Contract(CONTRACT, ABI, provider);
+
+    const latestBlock = await provider.getBlockNumber();
+
+    const filter = contract.filters.Minted();
+    const events: ethers.EventLog[] = [];
+    for (let start = DEPLOY_BLOCK; start <= latestBlock; start += CHUNK_SIZE + 1) {
+      const end = Math.min(start + CHUNK_SIZE, latestBlock);
+      const chunk = await contract.queryFilter(filter, start, end);
+      events.push(...(chunk as ethers.EventLog[]));
+    }
+
+    const tokens = events.map((event) => {
+      const tokenId = event.args[0].toString();
+      const to = event.args[1];
+      const tokenType = Number(event.args[2]);
+      const soulbound = event.args[3];
+      const tokenURI = event.args[4];
+
+      let name = null;
+      if (tokenURI.startsWith("data:application/json;base64,")) {
+        try {
+          const meta = JSON.parse(
+            Buffer.from(tokenURI.replace("data:application/json;base64,", ""), "base64").toString()
+          );
+          name = meta.name || null;
+        } catch {}
+      }
+
+      return {
+        tokenId: Number(tokenId),
+        recipient: to,
+        tokenType: TOKEN_TYPES[tokenType] || `Unknown(${tokenType})`,
+        soulbound,
+        name,
+        block: event.blockNumber,
+        txHash: event.transactionHash,
+      };
+    });
+
+    res.status(200).json({
+      totalMinted: tokens.length,
+      contract: CONTRACT,
+      chain: "Base",
+      chainId: 8453,
+      tokens: tokens.reverse(),
+    });
+  } catch (err: any) {
+    res.status(500).json({ error: err.message || "Failed to fetch feed" });
+  }
+}

package/api/sponsor.ts

@@ -0,0 +1,106 @@
+import type { VercelRequest, VercelResponse } from "@vercel/node";
+import { ethers } from "ethers";
+
+const PRIVATE_KEY = process.env.SPONSORED_KEY;
+const RPC_URL = process.env.BASE_RPC_URL || "https://mainnet.base.org";
+const CONTRACT = process.env.MINT_FACTORY_ADDRESS || "0x12a1c11a0b2860f64e7d8df20989f97d40de7f2c";
+
+// Rate limiting: per-address and global
+const addrLimits = new Map<string, { count: number; resetAt: number }>();
+const globalState = { count: 0, resetAt: 0 };
+const ADDR_LIMIT = 10;       // 10 mints per address per hour
+const GLOBAL_HOUR_LIMIT = 50; // 50 mints per hour
+const GLOBAL_DAY_LIMIT = 500; // 500 mints per day
+const HOUR_MS = 60 * 60 * 1000;
+
+const dailyState = { count: 0, resetAt: 0 };
+
+function checkRateLimit(recipient: string): string | null {
+  const now = Date.now();
+
+  // Per-address hourly limit
+  const addr = addrLimits.get(recipient);
+  if (!addr || now > addr.resetAt) {
+    addrLimits.set(recipient, { count: 1, resetAt: now + HOUR_MS });
+  } else if (addr.count >= ADDR_LIMIT) {
+    return `Address rate limited (${ADDR_LIMIT}/hour). Try again later.`;
+  } else {
+    addr.count++;
+  }
+
+  // Global hourly limit
+  if (now > globalState.resetAt) {
+    globalState.count = 1;
+    globalState.resetAt = now + HOUR_MS;
+  } else if (globalState.count >= GLOBAL_HOUR_LIMIT) {
+    return `Global hourly limit reached (${GLOBAL_HOUR_LIMIT}/hour). Try again later.`;
+  } else {
+    globalState.count++;
+  }
+
+  // Global daily limit
+  if (now > dailyState.resetAt) {
+    dailyState.count = 1;
+    dailyState.resetAt = now + 24 * HOUR_MS;
+  } else if (dailyState.count >= GLOBAL_DAY_LIMIT) {
+    return `Global daily limit reached (${GLOBAL_DAY_LIMIT}/day). Try again tomorrow.`;
+  } else {
+    dailyState.count++;
+  }
+
+  return null;
+}
+
+export default async function handler(req: VercelRequest, res: VercelResponse) {
+  if (req.method !== "POST") {
+    return res.status(405).json({ error: "POST only" });
+  }
+
+  if (!PRIVATE_KEY) {
+    return res.status(503).json({ error: "Sponsored minting not configured" });
+  }
+
+  const { to, calldata, value, estimatedGas, recipient } = req.body || {};
+
+  if (!to || !calldata || !recipient) {
+    return res.status(400).json({ error: "Missing required fields: to, calldata, recipient" });
+  }
+
+  if (!ethers.isAddress(to) || !ethers.isAddress(recipient)) {
+    return res.status(400).json({ error: "Invalid address" });
+  }
+
+  // Verify the target is our contract
+  if (to.toLowerCase() !== CONTRACT.toLowerCase()) {
+    return res.status(400).json({ error: "Invalid contract target" });
+  }
+
+  const rateLimitError = checkRateLimit(recipient.toLowerCase());
+  if (rateLimitError) {
+    return res.status(429).json({ error: rateLimitError });
+  }
+
+  try {
+    const provider = new ethers.JsonRpcProvider(RPC_URL);
+    const wallet = new ethers.Wallet(PRIVATE_KEY, provider);
+
+    const tx = await wallet.sendTransaction({
+      to,
+      data: calldata,
+      value: BigInt(value || "0"),
+      gasLimit: estimatedGas || 600000,
+    });
+
+    const receipt = await tx.wait();
+
+    return res.status(200).json({
+      txHash: receipt!.hash,
+      blockNumber: receipt!.blockNumber,
+      gasUsed: receipt!.gasUsed.toString(),
+      explorer: `https://basescan.org/tx/${receipt!.hash}`,
+    });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return res.status(500).json({ error: `Transaction failed: ${message}` });
+  }
+}