mint-day 0.3.0

package/dist/tools/mint.js

@@ -0,0 +1,425 @@
+import { createHash } from "crypto";
+import { z } from "zod";
+import { ethers } from "ethers";
+import { TokenType, TOKEN_TYPE_NAMES } from "../types.js";
+import { classifyIntent } from "../services/classifier.js";
+import { CalldataService } from "../services/calldata.js";
+import { resolveImage } from "../services/image-upload.js";
+import { resolveEns, looksLikeEns } from "../services/ens.js";
+// Intent cache: preview mintId -> frozen intent
+const intentCache = new Map();
+const CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
+function cacheMintId(intent) {
+    const hash = createHash("sha256")
+        .update(JSON.stringify(intent))
+        .digest("hex")
+        .slice(0, 12);
+    intentCache.set(hash, { intent, expiresAt: Date.now() + CACHE_TTL_MS });
+    return hash;
+}
+function getCachedIntent(mintId) {
+    const entry = intentCache.get(mintId);
+    if (!entry)
+        return null;
+    if (Date.now() > entry.expiresAt) {
+        intentCache.delete(mintId);
+        return null;
+    }
+    return entry.intent;
+}
+// --- Rate limiter (in-memory, resets on process restart) ---
+const LIMITS = {
+    perAddress: 10,
+    perHour: 50,
+    perDay: 500,
+};
+const addressMints = new Map();
+const hourlyWindow = { count: 0, resetAt: Date.now() + 60 * 60 * 1000 };
+const dailyWindow = { count: 0, resetAt: Date.now() + 24 * 60 * 60 * 1000 };
+function checkRateLimit(address) {
+    const now = Date.now();
+    const addr = address.toLowerCase();
+    // Reset windows if expired
+    if (now >= hourlyWindow.resetAt) {
+        hourlyWindow.count = 0;
+        hourlyWindow.resetAt = now + 60 * 60 * 1000;
+    }
+    if (now >= dailyWindow.resetAt) {
+        dailyWindow.count = 0;
+        dailyWindow.resetAt = now + 24 * 60 * 60 * 1000;
+        addressMints.clear(); // reset per-address counts daily
+    }
+    const addrCount = addressMints.get(addr) || 0;
+    if (addrCount >= LIMITS.perAddress) {
+        return { allowed: false, reason: `Address limit reached (${LIMITS.perAddress} sponsored mints per address per day)` };
+    }
+    if (hourlyWindow.count >= LIMITS.perHour) {
+        return { allowed: false, reason: `Hourly limit reached (${LIMITS.perHour} sponsored mints per hour)` };
+    }
+    if (dailyWindow.count >= LIMITS.perDay) {
+        return { allowed: false, reason: `Daily limit reached (${LIMITS.perDay} sponsored mints per day)` };
+    }
+    return {
+        allowed: true,
+        remaining: {
+            address: LIMITS.perAddress - addrCount - 1,
+            hourly: LIMITS.perHour - hourlyWindow.count - 1,
+            daily: LIMITS.perDay - dailyWindow.count - 1,
+        },
+    };
+}
+function recordMint(address) {
+    const addr = address.toLowerCase();
+    addressMints.set(addr, (addressMints.get(addr) || 0) + 1);
+    hourlyWindow.count++;
+    dailyWindow.count++;
+}
+// --- Schema + Handler ---
+export const mintSchema = {
+    description: z
+        .string()
+        .optional()
+        .describe("What to mint, in plain English. Required for new mints, omit when confirming with mintId."),
+    tokenType: z
+        .enum(["Identity", "Attestation", "Credential", "Receipt", "Pass"])
+        .optional()
+        .describe("Token type. If provided with soulbound, skips LLM classification."),
+    recipient: z
+        .string()
+        .optional()
+        .describe("Ethereum address or ENS name to receive the token. Required unless DEFAULT_RECIPIENT is set in server config."),
+    soulbound: z
+        .boolean()
+        .optional()
+        .describe("Whether the token is non-transferable. Defaults based on token type."),
+    image: z
+        .string()
+        .optional()
+        .describe("Image for visual tokens. Accepts: URL, local file path (/path/to/image.png or ~/image.png), or base64 data URI. Local files and base64 are auto-uploaded to Imgur if IMGUR_CLIENT_ID is set."),
+    animation_url: z
+        .string()
+        .optional()
+        .describe("Animation URL for rich media tokens (video, audio, HTML, generative art)."),
+    mintId: z
+        .string()
+        .optional()
+        .describe("Confirmation ID from a previous preview. Provide this to confirm and get calldata."),
+    metadata: z
+        .record(z.string(), z.unknown())
+        .optional()
+        .describe("Additional key-value metadata. Supports strings, arrays, and objects (e.g. capabilities: ['mint'])."),
+};
+export async function handleMint(params, calldataService, defaultRecipient, userKey = "", sponsored = {
+    sponsoredKey: "", sponsoredContract: "", sponsoredRpc: "", sponsoredChain: 8453,
+    fallbackContract: "", fallbackRpc: "", fallbackChain: 84532,
+}) {
+    const hasRecipient = !!params.recipient;
+    const sponsoredGas = !userKey;
+    // Confirmation path: replay cached intent
+    if (params.mintId) {
+        const cached = getCachedIntent(params.mintId);
+        if (!cached) {
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({ error: "mintId not found or expired. Start a new mint." }, null, 2),
+                    }],
+            };
+        }
+        intentCache.delete(params.mintId);
+        // Sponsored mode: check rate limits before submitting
+        if (sponsoredGas) {
+            const limit = checkRateLimit(cached.recipient);
+            if (limit.allowed) {
+                // Sponsored mainnet mint
+                const sponsoredService = new CalldataService(sponsored.sponsoredRpc, sponsored.sponsoredContract, sponsored.sponsoredChain);
+                const result = await sponsoredService.buildMintCalldata(cached);
+                try {
+                    const wallet = new ethers.Wallet(sponsored.sponsoredKey, sponsoredService.provider);
+                    const tx = await wallet.sendTransaction({
+                        to: result.to,
+                        data: result.calldata,
+                        value: BigInt(result.value),
+                        gasLimit: result.estimatedGas,
+                    });
+                    const receipt = await tx.wait();
+                    recordMint(cached.recipient);
+                    return {
+                        content: [{
+                                type: "text",
+                                text: JSON.stringify({
+                                    status: "minted",
+                                    txHash: receipt.hash,
+                                    blockNumber: receipt.blockNumber,
+                                    gasUsed: receipt.gasUsed.toString(),
+                                    tokenType: result.tokenType,
+                                    soulbound: result.soulbound,
+                                    recipient: cached.recipient,
+                                    chain: "Base",
+                                    explorer: `https://basescan.org/tx/${receipt.hash}`,
+                                }, null, 2),
+                            }],
+                    };
+                }
+                catch (err) {
+                    const message = err instanceof Error ? err.message : String(err);
+                    // On tx failure (e.g. sponsored wallet out of gas), fall back to calldata
+                    const fallbackService = new CalldataService(sponsored.sponsoredRpc, sponsored.sponsoredContract, sponsored.sponsoredChain);
+                    const fallbackResult = await fallbackService.buildMintCalldata(cached);
+                    return {
+                        content: [{
+                                type: "text",
+                                text: JSON.stringify({
+                                    status: "calldata",
+                                    reason: `Sponsored mint failed (${message}). Returning calldata for you to submit.`,
+                                    to: fallbackResult.to,
+                                    calldata: fallbackResult.calldata,
+                                    value: fallbackResult.value,
+                                    estimatedGas: fallbackResult.estimatedGas,
+                                    chainId: fallbackResult.chainId,
+                                    tokenType: fallbackResult.tokenType,
+                                    soulbound: fallbackResult.soulbound,
+                                }, null, 2),
+                            }],
+                    };
+                }
+            }
+            else {
+                // Rate limit exceeded: return calldata on mainnet (user pays gas)
+                const mainnetService = new CalldataService(sponsored.sponsoredRpc, sponsored.sponsoredContract, sponsored.sponsoredChain);
+                const result = await mainnetService.buildMintCalldata(cached);
+                return {
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify({
+                                status: "calldata",
+                                reason: limit.reason,
+                                message: "Sponsored gas limit reached. Here's the calldata to submit with your own wallet.",
+                                to: result.to,
+                                calldata: result.calldata,
+                                value: result.value,
+                                estimatedGas: result.estimatedGas,
+                                chainId: result.chainId,
+                                tokenType: result.tokenType,
+                                soulbound: result.soulbound,
+                                chain: "Base",
+                                setup: "Save a private key to ~/.mint-day/credentials for unlimited self-funded mints.",
+                            }, null, 2),
+                        }],
+                };
+            }
+        }
+        // User-key mode: sign and submit with user's key
+        if (userKey) {
+            const result = await calldataService.buildMintCalldata(cached);
+            try {
+                const wallet = new ethers.Wallet(userKey, calldataService.provider);
+                const tx = await wallet.sendTransaction({
+                    to: result.to,
+                    data: result.calldata,
+                    value: BigInt(result.value),
+                    gasLimit: result.estimatedGas,
+                });
+                const receipt = await tx.wait();
+                return {
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify({
+                                status: "minted",
+                                txHash: receipt.hash,
+                                blockNumber: receipt.blockNumber,
+                                gasUsed: receipt.gasUsed.toString(),
+                                tokenType: result.tokenType,
+                                soulbound: result.soulbound,
+                                recipient: cached.recipient,
+                                chain: "Base",
+                                explorer: `https://basescan.org/tx/${receipt.hash}`,
+                            }, null, 2),
+                        }],
+                };
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return {
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify({ error: `Transaction failed: ${message}` }, null, 2),
+                        }],
+                };
+            }
+        }
+        // Calldata-only mode (recipient provided, no key)
+        const result = await calldataService.buildMintCalldata(cached);
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        status: "calldata",
+                        to: result.to,
+                        calldata: result.calldata,
+                        value: result.value,
+                        estimatedGas: result.estimatedGas,
+                        chainId: result.chainId,
+                        tokenType: result.tokenType,
+                        soulbound: result.soulbound,
+                    }, null, 2),
+                }],
+        };
+    }
+    if (!params.description) {
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({ error: "description is required for new mints." }, null, 2),
+                }],
+        };
+    }
+    let recipient = params.recipient || defaultRecipient;
+    // Resolve ENS names to addresses
+    if (recipient && looksLikeEns(recipient)) {
+        try {
+            const resolved = await resolveEns(recipient);
+            recipient = resolved;
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({ error: message }, null, 2),
+                    }],
+            };
+        }
+    }
+    if (!recipient) {
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        status: "setup_required",
+                        message: "mint.day needs a wallet to sign transactions.",
+                        options: [
+                            {
+                                recommended: true,
+                                method: "Save a private key to ~/.mint-day/credentials",
+                                steps: [
+                                    "Generate a wallet: node -e \"console.log(require('ethers').Wallet.createRandom().privateKey)\"",
+                                    "Save it: mkdir -p ~/.mint-day && echo '0xYOUR_KEY' > ~/.mint-day/credentials && chmod 600 ~/.mint-day/credentials",
+                                    "Fund the address with a small amount of ETH on Base (gas is < $0.01 per mint)",
+                                    "Restart the MCP server"
+                                ]
+                            },
+                            {
+                                method: "Use your own signer (AgentKit, Lit Protocol, etc.)",
+                                steps: [
+                                    "Pass a recipient address in each mint call",
+                                    "mint.day returns calldata for your signer to submit",
+                                    "Works with Coinbase AgentKit, Lit Protocol, Privy, or any EVM wallet"
+                                ]
+                            }
+                        ]
+                    }, null, 2),
+                }],
+        };
+    }
+    // Validate address
+    if (!ethers.isAddress(recipient)) {
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({ error: `Invalid Ethereum address: ${recipient}` }, null, 2),
+                }],
+        };
+    }
+    // Resolve image: local files and base64 get uploaded to Imgur (if configured)
+    let resolvedImage = params.image;
+    let imageUploaded = false;
+    if (params.image) {
+        try {
+            const result = await resolveImage(params.image);
+            resolvedImage = result.url;
+            imageUploaded = result.uploaded;
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({ error: `Image resolution failed: ${message}` }, null, 2),
+                    }],
+            };
+        }
+    }
+    let intent;
+    if (params.tokenType !== undefined) {
+        const typeIndex = TOKEN_TYPE_NAMES.indexOf(params.tokenType);
+        const tokenType = typeIndex >= 0 ? typeIndex : TokenType.Attestation;
+        const defaultSoulbound = tokenType === TokenType.Attestation || tokenType === TokenType.Credential;
+        const meta = {
+            name: params.description,
+            description: params.description,
+            tokenType: TOKEN_TYPE_NAMES[tokenType],
+            soulbound: params.soulbound ?? defaultSoulbound,
+            creator: recipient,
+            recipient,
+            timestamp: new Date().toISOString(),
+            chainId: 8453,
+            mintday_version: "1",
+            ...(resolvedImage ? { image: resolvedImage } : {}),
+            ...(params.animation_url ? { animation_url: params.animation_url } : {}),
+            ...(params.metadata || {}),
+        };
+        // ERC-8004 defaults for Identity tokens
+        if (tokenType === TokenType.Identity) {
+            if (!meta.did)
+                meta.did = `did:pkh:eip155:8453:${recipient}`;
+            if (!meta.capabilities)
+                meta.capabilities = [];
+            if (!meta.endpoints)
+                meta.endpoints = [];
+        }
+        intent = {
+            tokenType,
+            soulbound: params.soulbound ?? defaultSoulbound,
+            recipient,
+            metadata: meta,
+        };
+    }
+    else {
+        intent = await classifyIntent(params.description, recipient);
+        if (resolvedImage)
+            intent.metadata.image = resolvedImage;
+        if (params.animation_url)
+            intent.metadata.animation_url = params.animation_url;
+        if (params.metadata) {
+            Object.assign(intent.metadata, params.metadata);
+        }
+    }
+    // Cache intent and return preview
+    const mintId = cacheMintId(intent);
+    const preview = {
+        status: "preview",
+        mintId,
+        message: `I'll mint a ${TOKEN_TYPE_NAMES[intent.tokenType]} token${intent.soulbound ? " (soulbound)" : ""} to ${intent.recipient}.`,
+        tokenType: TOKEN_TYPE_NAMES[intent.tokenType],
+        soulbound: intent.soulbound,
+        recipient: intent.recipient,
+        name: intent.metadata.name,
+    };
+    if (intent.metadata.image) {
+        preview.image = intent.metadata.image;
+        if (imageUploaded)
+            preview.imageUploaded = true;
+    }
+    if (intent.metadata.animation_url)
+        preview.animation_url = intent.metadata.animation_url;
+    if (intent.missingFields?.length) {
+        preview.missingFields = intent.missingFields;
+        preview.hint = "Identity tokens (ERC-8004) should include capabilities[], endpoints[], and did. Provide these in metadata for full compliance.";
+    }
+    preview.chain = "Base";
+    preview.instruction = "Call mint with mintId to confirm.";
+    return {
+        content: [{ type: "text", text: JSON.stringify(preview, null, 2) }],
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,39 @@
+export declare enum TokenType {
+    Identity = 0,
+    Attestation = 1,
+    Credential = 2,
+    Receipt = 3,
+    Pass = 4
+}
+export declare const TOKEN_TYPE_NAMES: readonly ["Identity", "Attestation", "Credential", "Receipt", "Pass"];
+export interface MintIntent {
+    tokenType: TokenType;
+    soulbound: boolean;
+    recipient: string;
+    metadata: TokenMetadata;
+    missingFields?: string[];
+}
+export interface TokenMetadata {
+    name: string;
+    description: string;
+    tokenType: string;
+    soulbound: boolean;
+    creator: string;
+    recipient: string;
+    timestamp: string;
+    chainId: number;
+    mintday_version: string;
+    image?: string;
+    animation_url?: string;
+    [key: string]: unknown;
+}
+export interface CalldataResult {
+    to: string;
+    calldata: string;
+    value: string;
+    estimatedGas: number;
+    chainId: number;
+    metadata: TokenMetadata;
+    tokenType: string;
+    soulbound: boolean;
+}

package/dist/types.js

@@ -0,0 +1,9 @@
+export var TokenType;
+(function (TokenType) {
+    TokenType[TokenType["Identity"] = 0] = "Identity";
+    TokenType[TokenType["Attestation"] = 1] = "Attestation";
+    TokenType[TokenType["Credential"] = 2] = "Credential";
+    TokenType[TokenType["Receipt"] = 3] = "Receipt";
+    TokenType[TokenType["Pass"] = 4] = "Pass";
+})(TokenType || (TokenType = {}));
+export const TOKEN_TYPE_NAMES = ["Identity", "Attestation", "Credential", "Receipt", "Pass"];

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "mint-day",
+  "version": "0.3.0",
+  "description": "Agent-native minting on Base. One tool call, any token type.",
+  "main": "dist/index.js",
+  "bin": {
+    "mint-day": "dist/index.js"
+  },
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "build": "tsc",
+    "start": "node dist/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "agents",
+    "nft",
+    "minting",
+    "base",
+    "ethereum"
+  ],
+  "author": "Jordan Lyall",
+  "license": "MIT",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "type": "module",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "dotenv": "^17.3.1",
+    "ethers": "^6.16.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "@vercel/node": "^5.6.15",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  }
+}