solforge 0.1.1 → 0.1.2

package/README.md

@@ -13,6 +13,7 @@
 - 🌐 **Port management** - Automatic port allocation and conflict resolution
 - 📝 **Configuration-driven** - JSON-based configuration for reproducible environments
 - 🎨 **Beautiful CLI** - Colorful, intuitive command-line interface
+- 🌐 **REST API** - Background API server for programmatic access to validator operations
 
 ## 🚀 Quick Start
 
@@ -66,10 +67,33 @@ bun run install:binary
    solforge stop --all
    ```
 
+### API Server
+
+SolForge automatically starts a REST API server alongside your validator, providing programmatic access to validator operations:
+
+```bash
+# API server starts automatically with the validator
+solforge start
+
+# API available at http://127.0.0.1:3000/api
+curl http://127.0.0.1:3000/api/health
+
+# Mint tokens via API
+curl -X POST http://127.0.0.1:3000/api/tokens/USDC/mint \
+  -H "Content-Type: application/json" \
+  -d '{"walletAddress": "YOUR_WALLET_ADDRESS", "amount": 1000}'
+
+# Get wallet balances
+curl http://127.0.0.1:3000/api/wallet/YOUR_WALLET_ADDRESS/balances
+```
+
+For complete API documentation, see [API Documentation](docs/API.md).
+
 ## 📖 Documentation
 
 ### 📚 Additional Documentation
 
+- [API Documentation](docs/API.md) - REST API endpoints and usage examples
 - [Configuration Guide](docs/CONFIGURATION.md) - Detailed configuration options and examples
 - [Troubleshooting Guide](#-troubleshooting) - Common issues and solutions
 
@@ -178,18 +202,31 @@ solforge add-program --program-id <address> --name <name>
 - `--name <name>` - Friendly name for the program
 - `--no-interactive` - Run in non-interactive mode
 
-#### `solforge transfer [options]`
+#### `solforge mint [options]`
 
-Interactively transfer tokens from mint authority to any address.
+Interactively mint tokens to any wallet address.
 
 ```bash
-solforge transfer                                    # Use default RPC
-solforge transfer --rpc-url http://localhost:8899   # Custom RPC
+solforge mint                                        # Interactive mode
+solforge mint --symbol USDC --wallet <address> --amount 1000  # CLI mode
+solforge mint --rpc-url http://localhost:8899       # Custom RPC
 ```
 
 **Options:**
 
 - `--rpc-url <url>` - RPC URL to use (default: "http://127.0.0.1:8899")
+- `--symbol <symbol>` - Token symbol to mint
+- `--wallet <address>` - Wallet address to mint to
+- `--amount <amount>` - Amount to mint
+
+**Interactive Mode:**
+When run without arguments, `solforge mint` will:
+
+- Display available cloned tokens
+- Allow you to select which token to mint
+- Prompt for recipient wallet address
+- Prompt for amount to mint
+- Handle SPL token account creation automatically
 
 #### `solforge reset`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solforge",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Solana localnet orchestration tool for cloning mainnet programs and tokens",
   "module": "index.ts",
   "type": "module",

package/src/api-server-entry.ts

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+
+import { APIServer } from "./services/api-server.js";
+import { configManager } from "./config/manager.js";
+import chalk from "chalk";
+
+async function main() {
+  try {
+    // Parse command line arguments
+    const args = process.argv.slice(2);
+    const portIndex = args.indexOf("--port");
+    const configIndex = args.indexOf("--config");
+    const rpcIndex = args.indexOf("--rpc-url");
+    const faucetIndex = args.indexOf("--faucet-url");
+    const workDirIndex = args.indexOf("--work-dir");
+
+    if (
+      portIndex === -1 ||
+      configIndex === -1 ||
+      rpcIndex === -1 ||
+      faucetIndex === -1 ||
+      workDirIndex === -1 ||
+      !args[portIndex + 1] ||
+      !args[configIndex + 1] ||
+      !args[rpcIndex + 1] ||
+      !args[faucetIndex + 1] ||
+      !args[workDirIndex + 1]
+    ) {
+      console.error(
+        "Usage: api-server-entry --port <port> --config <config-path> --rpc-url <url> --faucet-url <url> --work-dir <dir>"
+      );
+      process.exit(1);
+    }
+
+    const port = parseInt(args[portIndex + 1]!);
+    const configPath = args[configIndex + 1]!;
+    const rpcUrl = args[rpcIndex + 1]!;
+    const faucetUrl = args[faucetIndex + 1]!;
+    const workDir = args[workDirIndex + 1]!;
+
+    // Load configuration
+    await configManager.load(configPath);
+    const config = configManager.getConfig();
+
+    // Create and start API server
+    const apiServer = new APIServer({
+      port,
+      validatorRpcUrl: rpcUrl,
+      validatorFaucetUrl: faucetUrl,
+      config,
+      workDir,
+    });
+
+    const result = await apiServer.start();
+
+    if (result.success) {
+      console.log(chalk.green(`🚀 API Server started on port ${port}`));
+
+      // Keep the process alive
+      process.on("SIGTERM", async () => {
+        console.log(
+          chalk.yellow("📡 API Server received SIGTERM, shutting down...")
+        );
+        await apiServer.stop();
+        process.exit(0);
+      });
+
+      process.on("SIGINT", async () => {
+        console.log(
+          chalk.yellow("📡 API Server received SIGINT, shutting down...")
+        );
+        await apiServer.stop();
+        process.exit(0);
+      });
+
+      // Keep process alive
+      setInterval(() => {}, 1000);
+    } else {
+      console.error(
+        chalk.red(`❌ Failed to start API server: ${result.error}`)
+      );
+      process.exit(1);
+    }
+  } catch (error) {
+    console.error(
+      chalk.red(
+        `❌ API Server error: ${
+          error instanceof Error ? error.message : String(error)
+        }`
+      )
+    );
+    process.exit(1);
+  }
+}
+
+main().catch((error) => {
+  console.error(
+    chalk.red(
+      `❌ Fatal error: ${
+        error instanceof Error ? error.message : String(error)
+      }`
+    )
+  );
+  process.exit(1);
+});

package/src/commands/mint.ts

@@ -0,0 +1,336 @@
+import { Command } from "commander";
+import chalk from "chalk";
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+import { input, select } from "@inquirer/prompts";
+import { runCommand } from "../utils/shell";
+import { Keypair, PublicKey } from "@solana/web3.js";
+
+interface TokenConfig {
+  symbol: string;
+  mainnetMint: string;
+  mintAmount: number;
+}
+
+interface ClonedToken {
+  config: TokenConfig;
+  mintAuthorityPath: string;
+  modifiedAccountPath: string;
+  mintAuthority: {
+    publicKey: string;
+    secretKey: number[];
+  };
+}
+
+export const mintCommand = new Command()
+  .name("mint")
+  .description("Interactively mint tokens to any wallet address")
+  .option("--rpc-url <url>", "RPC URL to use", "http://127.0.0.1:8899")
+  .option("--symbol <symbol>", "Token symbol to mint")
+  .option("--wallet <address>", "Wallet address to mint to")
+  .option("--amount <amount>", "Amount to mint")
+  .action(async (options) => {
+    try {
+      console.log(chalk.blue("🪙 Interactive Token Minting"));
+      console.log(chalk.gray("Mint tokens to any wallet address\n"));
+
+      // Check if solforge data exists
+      const workDir = ".solforge";
+      if (!existsSync(workDir)) {
+        console.error(
+          chalk.red("❌ No solforge data found. Run 'solforge start' first.")
+        );
+        process.exit(1);
+      }
+
+      // Load available tokens
+      const tokens = await loadAvailableTokens(workDir);
+
+      if (tokens.length === 0) {
+        console.error(
+          chalk.red(
+            "❌ No tokens found. Run 'solforge start' first to clone tokens."
+          )
+        );
+        process.exit(1);
+      }
+
+      // Display available tokens
+      console.log(chalk.cyan("📋 Available Tokens:"));
+      tokens.forEach((token, index) => {
+        console.log(
+          chalk.gray(
+            `  ${index + 1}. ${token.config.symbol} (${
+              token.config.mainnetMint
+            })`
+          )
+        );
+      });
+      console.log();
+
+      // Select token (or use provided symbol)
+      let selectedToken: ClonedToken;
+      if (options.symbol) {
+        const token = tokens.find(
+          (t) => t.config.symbol.toLowerCase() === options.symbol.toLowerCase()
+        );
+        if (!token) {
+          console.error(
+            chalk.red(`❌ Token ${options.symbol} not found in cloned tokens`)
+          );
+          process.exit(1);
+        }
+        selectedToken = token;
+        console.log(
+          chalk.gray(`Selected token: ${selectedToken.config.symbol}`)
+        );
+      } else {
+        selectedToken = await select({
+          message: "Select a token to mint:",
+          choices: tokens.map((token) => ({
+            name: `${token.config.symbol} (${token.config.mainnetMint})`,
+            value: token,
+          })),
+        });
+      }
+
+      // Get recipient address (or use provided wallet)
+      let recipientAddress: string;
+      if (options.wallet) {
+        recipientAddress = options.wallet;
+        // Validate wallet address
+        try {
+          new PublicKey(recipientAddress);
+        } catch {
+          console.error(chalk.red("❌ Invalid wallet address"));
+          process.exit(1);
+        }
+        console.log(chalk.gray(`Recipient wallet: ${recipientAddress}`));
+      } else {
+        recipientAddress = await input({
+          message: "Enter recipient wallet address:",
+          validate: (value: string) => {
+            if (!value.trim()) {
+              return "Please enter a valid address";
+            }
+            try {
+              new PublicKey(value.trim());
+              return true;
+            } catch {
+              return "Please enter a valid Solana address";
+            }
+          },
+        });
+      }
+
+      // Get amount to mint (or use provided amount)
+      let amount: string;
+      if (options.amount) {
+        const num = parseFloat(options.amount);
+        if (isNaN(num) || num <= 0) {
+          console.error(chalk.red("❌ Invalid amount"));
+          process.exit(1);
+        }
+        amount = options.amount;
+        console.log(chalk.gray(`Amount to mint: ${amount}`));
+      } else {
+        amount = await input({
+          message: "Enter amount to mint:",
+          validate: (value: string) => {
+            const num = parseFloat(value);
+            if (isNaN(num) || num <= 0) {
+              return "Please enter a valid positive number";
+            }
+            return true;
+          },
+        });
+      }
+
+      // Confirm minting if interactive
+      if (!options.symbol || !options.wallet || !options.amount) {
+        const confirm = await input({
+          message: `Confirm minting ${amount} ${selectedToken.config.symbol} to ${recipientAddress}? (y/N):`,
+          default: "N",
+        });
+
+        if (confirm.toLowerCase() !== "y" && confirm.toLowerCase() !== "yes") {
+          console.log(chalk.yellow("Minting cancelled."));
+          process.exit(0);
+        }
+      }
+
+      console.log(chalk.blue("🚀 Starting mint..."));
+
+      // Execute mint
+      await mintTokenToWallet(
+        selectedToken,
+        recipientAddress,
+        parseFloat(amount),
+        options.rpcUrl
+      );
+
+      console.log(
+        chalk.green(
+          `✅ Successfully minted ${amount} ${selectedToken.config.symbol} to ${recipientAddress}`
+        )
+      );
+    } catch (error) {
+      console.error(chalk.red(`❌ Mint failed: ${error}`));
+      process.exit(1);
+    }
+  });
+
+async function loadAvailableTokens(workDir: string): Promise<ClonedToken[]> {
+  const tokens: ClonedToken[] = [];
+
+  try {
+    // Load token config from sf.config.json
+    const configPath = "sf.config.json";
+    if (!existsSync(configPath)) {
+      throw new Error("sf.config.json not found in current directory");
+    }
+
+    const config = JSON.parse(readFileSync(configPath, "utf8"));
+    const tokenConfigs: TokenConfig[] = config.tokens || [];
+
+    // Load shared mint authority
+    const sharedMintAuthorityPath = join(workDir, "shared-mint-authority.json");
+    if (!existsSync(sharedMintAuthorityPath)) {
+      throw new Error("Shared mint authority not found");
+    }
+
+    const secretKeyArray = JSON.parse(
+      readFileSync(sharedMintAuthorityPath, "utf8")
+    );
+    const mintAuthorityKeypair = Keypair.fromSecretKey(
+      new Uint8Array(secretKeyArray)
+    );
+    const mintAuthority = {
+      publicKey: mintAuthorityKeypair.publicKey.toBase58(),
+      secretKey: Array.from(mintAuthorityKeypair.secretKey),
+    };
+
+    // Build cloned tokens list
+    for (const tokenConfig of tokenConfigs) {
+      const tokenDir = join(
+        workDir,
+        `token-${tokenConfig.symbol.toLowerCase()}`
+      );
+      const modifiedAccountPath = join(tokenDir, "modified.json");
+
+      if (existsSync(modifiedAccountPath)) {
+        tokens.push({
+          config: tokenConfig,
+          mintAuthorityPath: sharedMintAuthorityPath,
+          modifiedAccountPath,
+          mintAuthority,
+        });
+      }
+    }
+
+    return tokens;
+  } catch (error) {
+    throw new Error(`Failed to load tokens: ${error}`);
+  }
+}
+
+export async function mintTokenToWallet(
+  token: ClonedToken,
+  walletAddress: string,
+  amount: number,
+  rpcUrl: string
+): Promise<void> {
+  // Check if associated token account already exists (same pattern as token-cloner.ts)
+  console.log(chalk.gray(`🔍 Checking for existing token account...`));
+
+  const checkAccountsResult = await runCommand(
+    "spl-token",
+    ["accounts", "--owner", walletAddress, "--url", rpcUrl, "--output", "json"],
+    { silent: true }
+  );
+
+  let tokenAccountAddress = "";
+
+  if (checkAccountsResult.success && checkAccountsResult.stdout) {
+    try {
+      const accountsData = JSON.parse(checkAccountsResult.stdout);
+
+      // Look for existing token account for this mint
+      for (const account of accountsData.accounts || []) {
+        if (account.mint === token.config.mainnetMint) {
+          tokenAccountAddress = account.address;
+          console.log(
+            chalk.gray(
+              `ℹ️  Found existing token account: ${tokenAccountAddress}`
+            )
+          );
+          break;
+        }
+      }
+    } catch (error) {
+      // No existing accounts found or parsing error, will create new account
+    }
+  }
+
+  if (!tokenAccountAddress) {
+    // Account doesn't exist, create it (same pattern as token-cloner.ts)
+    console.log(chalk.gray(`🔧 Creating token account...`));
+
+    const createAccountResult = await runCommand(
+      "spl-token",
+      [
+        "create-account",
+        token.config.mainnetMint,
+        "--owner",
+        walletAddress,
+        "--fee-payer",
+        token.mintAuthorityPath,
+        "--url",
+        rpcUrl,
+      ],
+      { silent: false }
+    );
+
+    if (!createAccountResult.success) {
+      throw new Error(
+        `Failed to create token account: ${createAccountResult.stderr}`
+      );
+    }
+
+    // Extract token account address from create-account output
+    const match = createAccountResult.stdout.match(/Creating account (\S+)/);
+    tokenAccountAddress = match?.[1] || "";
+
+    if (!tokenAccountAddress) {
+      throw new Error(
+        "Failed to determine token account address from create-account output"
+      );
+    }
+
+    console.log(chalk.gray(`✅ Created token account: ${tokenAccountAddress}`));
+  }
+
+  // Now mint to the token account (same pattern as token-cloner.ts)
+  console.log(chalk.gray(`💰 Minting ${amount} tokens...`));
+
+  const result = await runCommand(
+    "spl-token",
+    [
+      "mint",
+      token.config.mainnetMint,
+      amount.toString(),
+      tokenAccountAddress,
+      "--mint-authority",
+      token.mintAuthorityPath,
+      "--fee-payer",
+      token.mintAuthorityPath,
+      "--url",
+      rpcUrl,
+    ],
+    { silent: false }
+  );
+
+  if (!result.success) {
+    throw new Error(`Failed to mint tokens: ${result.stderr}`);
+  }
+}

package/src/commands/start.ts

@@ -9,6 +9,7 @@ import { TokenCloner } from "../services/token-cloner.js";
 import { ProgramCloner } from "../services/program-cloner.js";
 import { processRegistry } from "../services/process-registry.js";
 import { portManager } from "../services/port-manager.js";
+
 import type { Config, TokenConfig, ProgramConfig } from "../types/config.js";
 import type { ClonedToken } from "../services/token-cloner.js";
 import type { RunningValidator } from "../services/process-registry.js";
@@ -334,6 +335,93 @@ export async function startCommand(debug: boolean = false): Promise<void> {
       debug
     );
 
+    // Find an available port for the API server
+    let apiServerPort = 3000;
+    while (!(await portManager.isPortAvailable(apiServerPort))) {
+      apiServerPort++;
+      if (apiServerPort > 3100) {
+        throw new Error("Could not find available port for API server");
+      }
+    }
+
+    // Start the API server as a background process
+    let apiServerPid: number | undefined;
+    let apiResult: { success: boolean; error?: string } = {
+      success: false,
+      error: "Not started",
+    };
+
+    try {
+      const currentDir = process.cwd();
+      const testpilotDir = join(__dirname, "..", "..");
+      const apiServerScript = join(testpilotDir, "src", "api-server-entry.ts");
+      const configPath =
+        configManager.getConfigPath() ?? join(currentDir, "sf.config.json");
+      const workDir = join(currentDir, ".solforge");
+
+      // Start API server in background using runCommand with nohup
+      const apiServerCommand = `nohup bun run "${apiServerScript}" --port ${apiServerPort} --config "${configPath}" --rpc-url "http://127.0.0.1:${config.localnet.port}" --faucet-url "http://127.0.0.1:${config.localnet.faucetPort}" --work-dir "${workDir}" > /dev/null 2>&1 &`;
+
+      const startResult = await runCommand("sh", ["-c", apiServerCommand], {
+        silent: !debug,
+        debug: debug,
+      });
+
+      if (startResult.success) {
+        // Wait a moment for the API server to start
+        await new Promise((resolve) => setTimeout(resolve, 3000));
+
+        // Test if the API server is responding
+        try {
+          const response = await fetch(
+            `http://127.0.0.1:${apiServerPort}/api/health`
+          );
+          if (response.ok) {
+            apiResult = { success: true };
+            // Get the PID of the API server process
+            const pidResult = await runCommand(
+              "pgrep",
+              ["-f", `api-server-entry.*--port ${apiServerPort}`],
+              { silent: true, debug: false }
+            );
+            if (pidResult.success && pidResult.stdout.trim()) {
+              apiServerPid = parseInt(pidResult.stdout.trim().split("\n")[0]);
+            }
+          } else {
+            apiResult = {
+              success: false,
+              error: `Health check failed: ${response.status}`,
+            };
+          }
+        } catch (error) {
+          apiResult = {
+            success: false,
+            error: `Health check failed: ${
+              error instanceof Error ? error.message : String(error)
+            }`,
+          };
+        }
+      } else {
+        apiResult = {
+          success: false,
+          error: `Failed to start API server: ${
+            startResult.stderr || "Unknown error"
+          }`,
+        };
+      }
+    } catch (error) {
+      apiResult = {
+        success: false,
+        error: error instanceof Error ? error.message : String(error),
+      };
+    }
+
+    if (!apiResult.success) {
+      console.warn(
+        chalk.yellow("⚠️  Failed to start API server:", apiResult.error)
+      );
+    }
+
     // Register the running validator
     const runningValidator: RunningValidator = {
       id: validatorId,
@@ -346,6 +434,11 @@ export async function startCommand(debug: boolean = false): Promise<void> {
       configPath: configManager.getConfigPath() || "./sf.config.json",
       startTime: new Date(),
       status: "running",
+      apiServerPort: apiResult.success ? apiServerPort : undefined,
+      apiServerUrl: apiResult.success
+        ? `http://127.0.0.1:${apiServerPort}`
+        : undefined,
+      apiServerPid: apiResult.success ? apiServerPid : undefined,
     };
 
     processRegistry.register(runningValidator);
@@ -363,6 +456,11 @@ export async function startCommand(debug: boolean = false): Promise<void> {
         `💰 Faucet URL: http://127.0.0.1:${config.localnet.faucetPort}`
       )
     );
+    if (apiResult.success) {
+      console.log(
+        chalk.cyan(`🚀 API Server: http://127.0.0.1:${apiServerPort}/api`)
+      );
+    }
 
     // Airdrop SOL to mint authority if tokens were cloned
     if (clonedTokens.length > 0) {
@@ -464,6 +562,34 @@ export async function startCommand(debug: boolean = false): Promise<void> {
     console.log(
       chalk.gray("  - Run `solforge stop --all` to stop all validators")
     );
+    if (apiResult.success) {
+      console.log(chalk.blue("\n🔌 API Endpoints:"));
+      console.log(
+        chalk.gray(
+          `  - GET  http://127.0.0.1:${apiServerPort}/api/tokens - List cloned tokens`
+        )
+      );
+      console.log(
+        chalk.gray(
+          `  - GET  http://127.0.0.1:${apiServerPort}/api/programs - List cloned programs`
+        )
+      );
+      console.log(
+        chalk.gray(
+          `  - POST http://127.0.0.1:${apiServerPort}/api/tokens/{symbol}/mint - Mint tokens`
+        )
+      );
+      console.log(
+        chalk.gray(
+          `  - POST http://127.0.0.1:${apiServerPort}/api/airdrop - Airdrop SOL`
+        )
+      );
+      console.log(
+        chalk.gray(
+          `  - GET  http://127.0.0.1:${apiServerPort}/api/wallet/{address}/balances - Get balances`
+        )
+      );
+    }
   } catch (error) {
     spinner.fail("Failed to start validator");
     console.error(chalk.red("❌ Unexpected error:"));