solwink-cli 1.0.0

package/README.md

@@ -0,0 +1,83 @@
+# 🌊 SolWink: The Ultimate Solana Blink Generator
+
+[![npm version](https://img.shields.io/npm/v/solwink.svg)](https://www.npmjs.com/package/solwink)
+
+**SolWink** is a lightning-fast, interactive CLI that scaffolds production-ready **Solana Actions & Blinks** in seconds. 
+
+Stop fighting with CORS headers, Next.js App Router bloat, and `X-Blockchain-Ids` validation. SolWink generates lightweight, pure Express.js backends specifically architected to work perfectly with [Dial.to](https://dial.to), Phantom, and X (Twitter) right out of the box.
+
+---
+
+## ⚡ Quick Start
+
+You don't need to install anything globally. Scaffold your first Blink instantly using `npx`:
+
+```bash
+npx create-solwink@latest
+# or
+npx solwink@latest
+Follow the beautiful interactive prompts to name your project, select your network, and inject your smart contract variables.
+
+Once generated, simply step into your project and run:
+
+Bash
+cd my-solwink-app
+npm install
+npm run dev
+✨ Why SolWink?
+Building Solana Blinks should be fun, not frustrating. SolWink focuses on Developer Velocity:
+
+Zero-Config Express Backend: We ditched the heavy frontend frameworks. SolWink generates pure, lightweight Node.js/Express servers designed exclusively for API route handling.
+
+Bulletproof CORS & Headers: Pre-configured with the exact X-Action-Version and Access-Control-Allow-Origin headers required by the Dialect validator.
+
+Dynamic Network Selection: Choose between Mainnet-Beta or Devnet via interactive CLI dropdowns. SolWink automatically maps and injects the correct Genesis Hash / Chain ID into your project.
+
+Smart Variable Injection: The CLI prompts you for your Treasury Wallet or Candy Machine ID and securely injects them directly into the generated codebase.
+
+🛠️ Phase 1 Templates
+SolWink currently ships with the two most highly requested use cases in the Solana ecosystem:
+
+💰 1. SOL Donation (Crowdfund)
+A dynamic Blink that allows users to send SOL to a specific treasury wallet.
+
+Features: Customizable donation buttons (e.g., 0.1 SOL, 0.5 SOL, 1 SOL) and a custom amount input field.
+
+CLI Inputs: Prompts for the destination Treasury Wallet address.
+
+🖼️ 2. NFT Mint (Metaplex Candy Machine)
+A fully integrated NFT minting Blink using the modern @metaplex-foundation/umi standard.
+
+Features: Direct integration with Candy Machine v2/v3, pre-configured Umi instance, and optimized image rendering for Twitter unfurls.
+
+CLI Inputs: Prompts for your specific Metaplex Candy Machine ID.
+
+📁 Generated Architecture
+SolWink generates a clean, "Headless" backend structure that is easy to deploy to Render, Railway, or Heroku:
+
+
+🚀 Roadmap (Phase 2 & Beyond)
+We are actively expanding the SolWink template library to become the standard scaffolding tool for Solana Actions:
+
+[ ] SPL Token Transfer: Support for sending USDC, BONK, and other custom tokens.
+
+[ ] Jupiter Swaps: Direct token-to-token swaps right inside the Blink.
+
+[ ] DAO Governance: On-chain voting for Realms/Snapshot.
+
+[ ] Token Gating: Access control and exclusive claims based on NFT ownership.
+
+🤝 Contributing
+Contributions, issues, and feature requests are welcome! Feel free to check the issues page.
+
+To develop locally:
+
+Clone the repository.
+
+Run npm install.
+
+Run npm run build.
+
+Run npm link to test the CLI globally on your machine.
+
+

package/dist/cli.js

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import consola from "consola";
+import fs from "fs-extra";
+import path from "path";
+import { fileURLToPath } from "url";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const program = new Command();
+program
+    .name("solwink")
+    .description("The ultimate Solana Blink generator")
+    .version("1.0.0");
+program.action(async () => {
+    consola.box("Welcome to SolWink - The Solana Blink Generator 🌊");
+    try {
+        const templateType = await consola.prompt("Which Blink template would you like to scaffold?", {
+            type: "select",
+            options: [
+                { label: "💰 SOL Donation (Crowdfund)", value: "donation" },
+                { label: "🖼️ NFT Mint (Metaplex Candy Machine)", value: "nft-mint" },
+            ],
+        });
+        const network = await consola.prompt("Which Solana cluster will this run on?", {
+            type: "select",
+            options: [
+                { label: "Mainnet (Production)", value: "mainnet-beta" },
+                { label: "Devnet (Testing)", value: "devnet" },
+            ],
+        });
+        const projectName = await consola.prompt("What is the name of your project?", {
+            type: "text",
+            default: "my-solwink-app",
+        });
+        let targetWallet = "";
+        let candyMachineId = "";
+        if (templateType === "donation") {
+            targetWallet = await consola.prompt("Enter the destination treasury wallet address:", {
+                type: "text",
+            });
+        }
+        else if (templateType === "nft-mint") {
+            candyMachineId = await consola.prompt("Enter your Metaplex Candy Machine ID:", {
+                type: "text",
+            });
+        }
+        const targetPath = path.join(process.cwd(), projectName);
+        const templatePath = path.join(__dirname, "..", "templates", templateType);
+        consola.start(`Initializing ${templateType} project in ./${projectName}...`);
+        if (!(await fs.pathExists(templatePath))) {
+            throw new Error(`Template folder not found at: ${templatePath}`);
+        }
+        const chainIds = {
+            "mainnet-beta": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
+            "devnet": "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1",
+        };
+        const selectedChainId = chainIds[network];
+        await fs.copy(templatePath, targetPath);
+        const routePath = path.join(targetPath, "api", "index.ts");
+        if (await fs.pathExists(routePath)) {
+            let routeContent = await fs.readFile(routePath, "utf8");
+            routeContent = routeContent.replace(/{{NETWORK}}/g, network);
+            routeContent = routeContent.replace(/{{CHAIN_ID}}/g, selectedChainId);
+            if (templateType === "donation") {
+                routeContent = routeContent.replace(/{{TREASURY_WALLET}}/g, targetWallet);
+            }
+            else if (templateType === "nft-mint") {
+                routeContent = routeContent.replace(/{{CANDY_MACHINE_ID}}/g, candyMachineId);
+            }
+            await fs.writeFile(routePath, routeContent);
+        }
+        consola.success(`Project initialized successfully! 🎉`);
+        consola.info(`\nNext steps:\n  cd ${projectName}\n  npm install\n  npm run dev\n`);
+    }
+    catch (err) {
+        consola.error("Project Initialization Failed!", err);
+    }
+});
+program.parse(process.argv);

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "solwink-cli",
+  "version": "1.0.0",
+  "description": "The ultimate interactive CLI to scaffold Solana Blinks and Actions",
+  "type": "module",
+  "bin": {
+    "solwink": "./dist/cli.js",
+    "create-solwink": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/cli.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "solana",
+    "blinks",
+    "actions",
+    "cli",
+    "generator",
+    "superteam"
+  ],
+  "author": "Kartik Angiras",
+  "license": "MIT",
+  "dependencies": {
+    "commander": "^12.1.0",
+    "consola": "^3.4.2",
+    "fs-extra": "^11.2.0"
+  },
+  "devDependencies": {
+    "@types/fs-extra": "^11.0.4",
+    "@types/node": "^20.0.0",
+    "typescript": "^5.9.3"
+  }
+}

package/templates/donation/api/index.ts

@@ -0,0 +1,123 @@
+import express from "express";
+import {
+  ActionGetResponse,
+  ActionPostRequest,
+  ActionPostResponse,
+} from "@solana/actions";
+import {
+  Connection,
+  PublicKey,
+  SystemProgram,
+  TransactionMessage,
+  VersionedTransaction,
+  clusterApiUrl,
+} from "@solana/web3.js";
+
+const app = express();
+app.use(express.json());
+
+const ACTION_HEADERS = {
+  "Access-Control-Allow-Origin": "*",
+  "Access-Control-Allow-Methods": "GET,POST,PUT,OPTIONS",
+  "Access-Control-Allow-Headers": "Content-Type, Authorization, Content-Encoding, Accept-Encoding",
+  "Access-Control-Expose-Headers": "X-Action-Version, X-Blockchain-Ids",
+  "X-Action-Version": "2.1.3",
+  "X-Blockchain-Ids": "{{CHAIN_ID}}",
+};
+
+app.use((req, res, next) => {
+  res.set(ACTION_HEADERS);
+  if (req.method === "OPTIONS") {
+    return res.status(200).end();
+  }
+  next();
+});
+
+app.get("/actions.json", (req, res) => {
+  res.json({
+    rules: [
+      { pathPattern: "/*", apiPath: "/api/donate" },
+      { pathPattern: "/api/donate", apiPath: "/api/donate" }
+    ]
+  });
+});
+
+app.get("/api/donate", (req, res) => {
+  const baseUrl = `${req.protocol}://${req.get("host")}`;
+
+  const payload: ActionGetResponse = {
+    type: "action",
+    icon: "https://ucarecdn.com/7aa46c85-08a4-4bc7-9376-88ec48bb1f43/-/preview/880x864/-/quality/smart/-/format/auto/", 
+    title: "Support the Project",
+    description: "Your SOL donation helps fund continuous open-source development.",
+    label: "Donate SOL",
+    links: {
+      actions: [
+        {
+          type: "transaction",
+          label: "Send Donation",
+          href: `${baseUrl}/api/donate?amount={amount}`,
+          parameters: [
+            { 
+              name: "amount", 
+              label: "Enter SOL amount", 
+              required: true 
+            }
+          ],
+        },
+      ],
+    },
+  };
+
+  res.json(payload);
+});
+
+app.post("/api/donate", async (req, res) => {
+  try {
+    const body: ActionPostRequest = req.body;
+    const donorPubkey = new PublicKey(body.account);
+
+    const amountStr = req.query.amount as string;
+    const amount = parseFloat(amountStr);
+
+    if (isNaN(amount) || amount <= 0) {
+      return res.status(400).json({ error: "Invalid amount entered." });
+    }
+
+    const connection = new Connection(clusterApiUrl("{{NETWORK}}" as any), "confirmed");
+    const DONATION_DESTINATION_WALLET = new PublicKey("{{TREASURY_WALLET}}"); 
+
+    const transferIx = SystemProgram.transfer({
+      fromPubkey: donorPubkey,
+      toPubkey: DONATION_DESTINATION_WALLET,
+      lamports: amount * 1_000_000_000,
+    });
+
+    const { blockhash } = await connection.getLatestBlockhash();
+
+    const messageV0 = new TransactionMessage({
+      payerKey: donorPubkey,
+      recentBlockhash: blockhash,
+      instructions: [transferIx],
+    }).compileToV0Message();
+
+    const transaction = new VersionedTransaction(messageV0);
+    const serializedTransaction = Buffer.from(transaction.serialize()).toString("base64");
+
+    const payload: ActionPostResponse = {
+      type: "transaction",
+      transaction: serializedTransaction,
+      message: `Successfully donated ${amount} SOL. Thank you!`,
+    };
+
+    res.json(payload);
+  } catch (err) {
+    console.error(err);
+    res.status(500).json({ error: "Failed to build transaction" });
+  }
+});
+
+const PORT = process.env.PORT || 8080;
+app.listen(PORT, () => {
+  console.log(`🚀 SolWink Donation Server running on port ${PORT}`);
+});

package/templates/donation/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "solwink-donation",
+  "version": "1.0.0",
+  "private": true,
+  "scripts": {
+    "dev": "ts-node api/index.ts"
+  },
+  "dependencies": {
+    "@metaplex-foundation/mpl-candy-machine": "^6.0.0",
+    "@metaplex-foundation/mpl-toolbox": "^0.9.4",
+    "@metaplex-foundation/umi": "^0.9.1",
+    "@metaplex-foundation/umi-bundle-defaults": "^0.9.1",
+    "@metaplex-foundation/umi-web3js-adapters": "^0.9.1",
+    "@solana/actions": "^1.6.6",
+    "@solana/web3.js": "^1.98.4",
+    "cors": "^2.8.5",
+    "express": "^4.19.2"
+  },
+  "devDependencies": {
+    "@types/cors": "^2.8.17",
+    "@types/express": "^4.17.21",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.0.0"
+  }
+}

package/templates/donation/public/actions.json

@@ -0,0 +1,12 @@
+{
+  "rules": [
+    {
+      "pathPattern": "/*",
+      "apiPath": "/api/donate"
+    },
+    {
+      "pathPattern": "/api/donate",
+      "apiPath": "/api/donate"
+    }
+  ]
+}

package/templates/donation/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "CommonJS",
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "outDir": "./dist"
+  },
+  "include": ["api/**/*.ts"]
+}

package/templates/nft-mint/api/index.ts

@@ -0,0 +1,123 @@
+import express from "express";
+import {
+  ActionGetResponse,
+  ActionPostRequest,
+  ActionPostResponse,
+} from "@solana/actions";
+import { clusterApiUrl } from "@solana/web3.js";
+
+
+import { createUmi } from "@metaplex-foundation/umi-bundle-defaults";
+import { fetchCandyMachine, mintV2, mplCandyMachine } from "@metaplex-foundation/mpl-candy-machine";
+import { createNoopSigner, generateSigner, publicKey, transactionBuilder } from "@metaplex-foundation/umi";
+import { setComputeUnitLimit } from "@metaplex-foundation/mpl-toolbox";
+import { toWeb3JsTransaction } from "@metaplex-foundation/umi-web3js-adapters";
+
+const app = express();
+app.use(express.json());
+
+const ACTION_HEADERS = {
+  "Access-Control-Allow-Origin": "*",
+  "Access-Control-Allow-Methods": "GET,POST,PUT,OPTIONS",
+  "Access-Control-Allow-Headers": "Content-Type, Authorization, Content-Encoding, Accept-Encoding",
+  "Access-Control-Expose-Headers": "X-Action-Version, X-Blockchain-Ids",
+  "X-Action-Version": "2.1.3",
+  "X-Blockchain-Ids": "{{CHAIN_ID}}",
+};
+
+app.use((req, res, next) => {
+  res.set(ACTION_HEADERS);
+  if (req.method === "OPTIONS") {
+    return res.status(200).end();
+  }
+  next();
+});
+
+app.get("/actions.json", (req, res) => {
+  res.json({
+    rules: [
+      { pathPattern: "/*", apiPath: "/api/mint" },
+      { pathPattern: "/api/mint", apiPath: "/api/mint" }
+    ]
+  });
+});
+
+app.get("/api/mint", (req, res) => {
+  const baseUrl = `${req.protocol}://${req.get("host")}`;
+
+  const payload: ActionGetResponse = {
+    type: "action",
+    icon: "https://metadata.y00ts.com/y/13877.png", 
+    title: "Mint Your Exclusive NFT",
+    description: "Mint a digital collectible directly from this Blink using Metaplex Candy Machine.",
+    label: "Mint NFT",
+    links: {
+      actions: [
+        { 
+          type: "transaction", 
+          label: "Mint NFT", 
+          href: `${baseUrl}/api/mint?amount={amount}`,
+          parameters: [
+            {
+              name: "amount", 
+              label: "Enter number of NFTs to mint",
+              required: true,
+            }
+          ],
+        }
+      ],
+    },
+  };
+
+  res.json(payload);
+} );
+
+app.post("/api/mint", async (req, res) => {
+  try {
+    const body: ActionPostRequest = req.body;
+    
+    const umi = createUmi(clusterApiUrl("{{NETWORK}}" as any)).use(mplCandyMachine());
+    const minterPubkey = publicKey(body.account);
+    const cmPubkey = publicKey("{{CANDY_MACHINE_ID}}"); 
+    
+    umi.use({
+      install(umi) {
+        umi.payer = createNoopSigner(minterPubkey);
+      }
+    });
+
+    const candyMachine = await fetchCandyMachine(umi, cmPubkey);
+    const nftSigner = generateSigner(umi);
+
+    const builder = transactionBuilder()
+      .add(setComputeUnitLimit(umi, { units: 800_000 })) 
+      .add(
+        mintV2(umi, {
+          candyMachine: candyMachine.publicKey,
+          nftMint: nftSigner,
+          collectionMint: candyMachine.collectionMint,
+          collectionUpdateAuthority: candyMachine.authority,
+        })
+      );
+
+    const umiTransaction = await builder.buildAndSign(umi);
+    const web3Transaction = toWeb3JsTransaction(umiTransaction);
+    const serializedTransaction = Buffer.from(web3Transaction.serialize()).toString("base64");
+
+    const payload: ActionPostResponse = {
+      type: "transaction",
+      transaction: serializedTransaction,
+      message: `Successfully minted NFT! Address: ${nftSigner.publicKey.toString().slice(0, 8)}...`,
+    };
+
+    res.json(payload);
+  } catch (err) {
+    console.error("Minting Error:", err);
+    res.status(500).json({ error: "Failed to build mint transaction." });
+  }
+});
+
+const PORT = process.env.PORT || 8080;
+app.listen(PORT, () => {
+  console.log(`🚀 SolWink NFT Server running on port ${PORT}`);
+});

package/templates/nft-mint/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "solwink-nft-mint",
+  "version": "1.0.0",
+  "private": true,
+  "scripts": {
+    "dev": "ts-node api/index.ts"
+  },
+  "dependencies": {
+    "@metaplex-foundation/mpl-candy-machine": "^6.0.0",
+    "@metaplex-foundation/mpl-toolbox": "^0.9.4",
+    "@metaplex-foundation/umi": "^0.9.1",
+    "@metaplex-foundation/umi-bundle-defaults": "^0.9.1",
+    "@metaplex-foundation/umi-web3js-adapters": "^0.9.1",
+    "@solana/actions": "^1.6.6",
+    "@solana/web3.js": "^1.98.4",
+    "cors": "^2.8.5",
+    "express": "^4.19.2"
+  },
+  "devDependencies": {
+    "@types/cors": "^2.8.17",
+    "@types/express": "^4.17.21",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.0.0"
+  }
+}

package/templates/nft-mint/public/actions.json

@@ -0,0 +1,12 @@
+{
+  "rules": [
+    {
+      "pathPattern": "/*",
+      "apiPath": "/api/mint"
+    },
+    {
+      "pathPattern": "/api/mint",
+      "apiPath": "/api/mint"
+    }
+  ]
+}

package/templates/nft-mint/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "CommonJS",
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "outDir": "./dist"
+  },
+  "include": ["api/**/*.ts"]
+}