solforge 0.1.5 → 0.1.7

package/README.md

@@ -1,5 +1,8 @@
 # SolForge
 
+[![npm version](https://badge.fury.io/js/solforge.svg)](https://badge.fury.io/js/solforge)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
 **SolForge** is a powerful Solana localnet orchestration tool that simplifies the process of setting up and managing local Solana development environments. It allows you to clone mainnet programs and tokens to your local validator, making it easy to develop and test Solana applications with real-world data.
 
 ## ✨ Features
@@ -15,15 +18,27 @@
 - 🎨 **Beautiful CLI** - Colorful, intuitive command-line interface
 - 🌐 **REST API** - Background API server for programmatic access to validator operations
 
-## 🚀 Quick Start
+## 📦 Installation
 
 ### Prerequisites
 
-- [Bun](https://bun.sh) runtime
 - [Solana CLI tools](https://docs.solana.com/cli/install-solana-cli-tools) installed and configured
-- Node.js 18+ (for compatibility)
+- Node.js 18+ or [Bun](https://bun.sh) runtime
 
-### Installation
+### Install from npm (Recommended)
+
+```bash
+# Install globally with npm
+npm install -g solforge
+
+# Or with bun
+bun install -g solforge
+
+# Or with yarn
+yarn global add solforge
+```
+
+### Install from Source
 
 ```bash
 # Clone the repository
@@ -33,14 +48,20 @@ cd solforge
 # Install dependencies
 bun install
 
-# Build the project
-bun run build
+# Build and install globally
+bun run build:npm
+npm install -g .
+```
 
-# Install globally (optional)
-bun run build:binary
-bun run install:binary
+### Verify Installation
+
+```bash
+solforge --version
+solforge --help
 ```
 
+## 🚀 Quick Start
+
 ### Basic Usage
 
 1. **Initialize a new project**:
@@ -78,8 +99,8 @@ 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 \
+# Mint tokens via API (using mint address)
+curl -X POST http://127.0.0.1:3000/api/tokens/EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v/mint \
   -H "Content-Type: application/json" \
   -d '{"walletAddress": "YOUR_WALLET_ADDRESS", "amount": 1000}'
 
@@ -121,11 +142,14 @@ Start a localnet validator with the current configuration.
 ```bash
 solforge start                # Start with default settings
 solforge start --debug        # Start with debug logging
+solforge start --network      # Make API server accessible over network
+solforge start --debug --network  # Debug mode + network access
 ```
 
 **Options:**
 
 - `--debug` - Enable debug logging to see detailed command output
+- `--network` - Make API server accessible over network (binds to 0.0.0.0 instead of 127.0.0.1)
 
 #### `solforge list`
 
@@ -228,6 +252,25 @@ When run without arguments, `solforge mint` will:
 - Prompt for amount to mint
 - Handle SPL token account creation automatically
 
+#### `solforge api-server [options]`
+
+Start the API server as a standalone service (without validator).
+
+```bash
+solforge api-server                                    # Start on default port 3000
+solforge api-server --port 8080                       # Custom port
+solforge api-server --host 0.0.0.0                    # Network accessible
+solforge api-server --rpc-url http://localhost:8899   # Custom RPC
+```
+
+**Options:**
+
+- `-p, --port <port>` - Port for API server (default: 3000)
+- `--host <host>` - Host to bind to (default: 127.0.0.1, use 0.0.0.0 for network access)
+- `--rpc-url <url>` - Validator RPC URL (default: http://127.0.0.1:8899)
+- `--faucet-url <url>` - Validator faucet URL (default: http://127.0.0.1:9900)
+- `--work-dir <dir>` - Work directory (default: ./.solforge)
+
 #### `solforge reset`
 
 Reset localnet ledger (coming soon).
@@ -275,7 +318,7 @@ Here's the complete schema:
     "faucetAccounts": ["YourWalletPublicKeyHere"],
     "port": 8899,
     "faucetPort": 9900,
-    "reset": true,
+    "reset": false,
     "logLevel": "info",
     "bindAddress": "127.0.0.1",
     "limitLedgerSize": 100000,

package/package.json

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

package/src/commands/init.ts

@@ -22,11 +22,11 @@ const defaultConfig: Config = {
     faucetAccounts: [],
     port: 8899,
     faucetPort: 9900,
-    reset: true,
+    reset: false,
     logLevel: "info",
     bindAddress: "127.0.0.1",
     quiet: false,
-    rpc: "https://mainnet.helius-rpc.com/?api-key=3a3b84ef-2985-4543-9d67-535eb707b6ec",
+    rpc: "https://api.mainnet-beta.solana.com",
     limitLedgerSize: 100000,
   },
 };

package/src/commands/mint.ts

@@ -5,22 +5,12 @@ 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[];
-  };
-}
+import {
+  loadClonedTokens,
+  findTokenBySymbol,
+  type ClonedToken,
+} from "../utils/token-loader.js";
+import type { TokenConfig } from "../types/config.js";
 
 export const mintCommand = new Command()
   .name("mint")
@@ -71,9 +61,7 @@ export const mintCommand = new Command()
       // Select token (or use provided symbol)
       let selectedToken: ClonedToken;
       if (options.symbol) {
-        const token = tokens.find(
-          (t) => t.config.symbol.toLowerCase() === options.symbol.toLowerCase()
-        );
+        const token = findTokenBySymbol(tokens, options.symbol);
         if (!token) {
           console.error(
             chalk.red(`❌ Token ${options.symbol} not found in cloned tokens`)
@@ -181,8 +169,6 @@ export const mintCommand = new Command()
   });
 
 async function loadAvailableTokens(workDir: string): Promise<ClonedToken[]> {
-  const tokens: ClonedToken[] = [];
-
   try {
     // Load token config from sf.config.json
     const configPath = "sf.config.json";
@@ -193,42 +179,8 @@ async function loadAvailableTokens(workDir: string): Promise<ClonedToken[]> {
     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;
+    // Use the shared token loader
+    return await loadClonedTokens(tokenConfigs, workDir);
   } catch (error) {
     throw new Error(`Failed to load tokens: ${error}`);
   }

package/src/commands/start.ts

@@ -6,11 +6,10 @@ import { join } from "path";
 import { runCommand, checkSolanaTools } from "../utils/shell.js";
 import { configManager } from "../config/manager.js";
 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 { Config, TokenConfig } from "../types/config.js";
 import type { ClonedToken } from "../services/token-cloner.js";
 import type { RunningValidator } from "../services/process-registry.js";
 
@@ -593,7 +592,7 @@ export async function startCommand(
       );
       console.log(
         chalk.gray(
-          `  - POST http://${endpointHost}:${apiServerPort}/api/tokens/{symbol}/mint - Mint tokens`
+          `  - POST http://${endpointHost}:${apiServerPort}/api/tokens/{mintAddress}/mint - Mint tokens`
         )
       );
       console.log(

package/src/services/api-server.ts

@@ -11,8 +11,12 @@ import { runCommand } from "../utils/shell.js";
 import { TokenCloner } from "./token-cloner.js";
 import { ProgramCloner } from "./program-cloner.js";
 import { mintTokenToWallet as mintTokenToWalletShared } from "../commands/mint.js";
+import {
+  loadClonedTokens,
+  findTokenByMint,
+  type ClonedToken,
+} from "../utils/token-loader.js";
 import type { Config } from "../types/config.js";
-import type { ClonedToken } from "./token-cloner.js";
 
 export interface APIServerConfig {
   port: number;
@@ -122,9 +126,9 @@ export class APIServer {
     });
 
     // Mint tokens to a wallet
-    router.post("/tokens/:symbol/mint", async (req, res) => {
+    router.post("/tokens/:mintAddress/mint", async (req, res) => {
       try {
-        const { symbol } = req.params;
+        const { mintAddress } = req.params;
         const { walletAddress, amount } = req.body;
 
         if (!walletAddress || !amount) {
@@ -133,6 +137,15 @@ export class APIServer {
           });
         }
 
+        // Validate mint address
+        try {
+          new PublicKey(mintAddress);
+        } catch {
+          return res.status(400).json({
+            error: "Invalid mint address",
+          });
+        }
+
         // Validate wallet address
         try {
           new PublicKey(walletAddress);
@@ -150,7 +163,7 @@ export class APIServer {
         }
 
         const result = await this.mintTokenToWallet(
-          symbol,
+          mintAddress,
           walletAddress,
           amount
         );
@@ -247,57 +260,10 @@ export class APIServer {
   }
 
   private async getClonedTokens(): Promise<ClonedToken[]> {
-    const clonedTokens: ClonedToken[] = [];
-
-    for (const tokenConfig of this.config.config.tokens) {
-      const tokenDir = join(
-        this.config.workDir,
-        `token-${tokenConfig.symbol.toLowerCase()}`
-      );
-      const modifiedAccountPath = join(tokenDir, "modified.json");
-      const sharedMintAuthorityPath = join(
-        this.config.workDir,
-        "shared-mint-authority.json"
-      );
-
-      if (
-        existsSync(modifiedAccountPath) &&
-        existsSync(sharedMintAuthorityPath)
-      ) {
-        try {
-          const mintAuthorityData = JSON.parse(
-            readFileSync(sharedMintAuthorityPath, "utf8")
-          );
-          let mintAuthority;
-
-          if (Array.isArray(mintAuthorityData)) {
-            const keypair = Keypair.fromSecretKey(
-              new Uint8Array(mintAuthorityData)
-            );
-            mintAuthority = {
-              publicKey: keypair.publicKey.toBase58(),
-              secretKey: Array.from(keypair.secretKey),
-            };
-          } else {
-            mintAuthority = mintAuthorityData;
-          }
-
-          clonedTokens.push({
-            config: tokenConfig,
-            mintAuthorityPath: sharedMintAuthorityPath,
-            modifiedAccountPath,
-            mintAuthority,
-          });
-        } catch (error) {
-          console.error(
-            `Failed to load cloned token ${tokenConfig.symbol}:`,
-            error
-          );
-        }
-      }
-    }
-
-    return clonedTokens;
+    return await loadClonedTokens(
+      this.config.config.tokens,
+      this.config.workDir
+    );
   }
 
   private async getClonedPrograms(): Promise<
@@ -327,17 +293,15 @@ export class APIServer {
   }
 
   private async mintTokenToWallet(
-    symbol: string,
+    mintAddress: string,
     walletAddress: string,
     amount: number
   ): Promise<any> {
     const clonedTokens = await this.getClonedTokens();
-    const token = clonedTokens.find(
-      (t) => t.config.symbol.toLowerCase() === symbol.toLowerCase()
-    );
+    const token = findTokenByMint(clonedTokens, mintAddress);
 
     if (!token) {
-      throw new Error(`Token ${symbol} not found in cloned tokens`);
+      throw new Error(`Token ${mintAddress} not found in cloned tokens`);
     }
 
     // Use the shared minting function from the mint command

package/src/utils/token-loader.ts

@@ -0,0 +1,115 @@
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+import { Keypair } from "@solana/web3.js";
+import type { TokenConfig } from "../types/config.js";
+
+export interface ClonedToken {
+  config: TokenConfig;
+  mintAuthorityPath: string;
+  modifiedAccountPath: string;
+  metadataAccountPath?: string;
+  mintAuthority: {
+    publicKey: string;
+    secretKey: number[];
+  };
+}
+
+/**
+ * Shared utility to load cloned tokens from the work directory.
+ * This ensures consistent token loading across CLI and API server.
+ */
+export async function loadClonedTokens(
+  tokenConfigs: TokenConfig[],
+  workDir: string = ".solforge"
+): Promise<ClonedToken[]> {
+  const clonedTokens: ClonedToken[] = [];
+
+  // Load shared mint authority
+  const sharedMintAuthorityPath = join(workDir, "shared-mint-authority.json");
+  let sharedMintAuthority: { publicKey: string; secretKey: number[] } | null =
+    null;
+
+  if (existsSync(sharedMintAuthorityPath)) {
+    try {
+      const fileContent = JSON.parse(
+        readFileSync(sharedMintAuthorityPath, "utf8")
+      );
+
+      if (Array.isArray(fileContent)) {
+        // New format: file contains just the secret key array
+        const keypair = Keypair.fromSecretKey(new Uint8Array(fileContent));
+        sharedMintAuthority = {
+          publicKey: keypair.publicKey.toBase58(),
+          secretKey: Array.from(keypair.secretKey),
+        };
+
+        // Check metadata for consistency
+        const metadataPath = join(workDir, "shared-mint-authority-meta.json");
+        if (existsSync(metadataPath)) {
+          const metadata = JSON.parse(readFileSync(metadataPath, "utf8"));
+          if (metadata.publicKey !== sharedMintAuthority.publicKey) {
+            sharedMintAuthority.publicKey = metadata.publicKey;
+          }
+        }
+      } else {
+        // Old format: file contains {publicKey, secretKey}
+        sharedMintAuthority = fileContent;
+      }
+    } catch (error) {
+      console.error("Failed to load shared mint authority:", error);
+      return [];
+    }
+  }
+
+  if (!sharedMintAuthority) {
+    return [];
+  }
+
+  // Load each token that has been cloned
+  for (const tokenConfig of tokenConfigs) {
+    const tokenDir = join(workDir, `token-${tokenConfig.symbol.toLowerCase()}`);
+    const modifiedAccountPath = join(tokenDir, "modified.json");
+    const metadataAccountPath = join(tokenDir, "metadata.json");
+
+    // Check if this token has already been cloned
+    if (existsSync(modifiedAccountPath)) {
+      const clonedToken: ClonedToken = {
+        config: tokenConfig,
+        mintAuthorityPath: sharedMintAuthorityPath,
+        modifiedAccountPath,
+        mintAuthority: sharedMintAuthority,
+      };
+
+      // Add metadata path if it exists
+      if (existsSync(metadataAccountPath)) {
+        clonedToken.metadataAccountPath = metadataAccountPath;
+      }
+
+      clonedTokens.push(clonedToken);
+    }
+  }
+
+  return clonedTokens;
+}
+
+/**
+ * Find a cloned token by its mint address
+ */
+export function findTokenByMint(
+  clonedTokens: ClonedToken[],
+  mintAddress: string
+): ClonedToken | undefined {
+  return clonedTokens.find((token) => token.config.mainnetMint === mintAddress);
+}
+
+/**
+ * Find a cloned token by its symbol
+ */
+export function findTokenBySymbol(
+  clonedTokens: ClonedToken[],
+  symbol: string
+): ClonedToken | undefined {
+  return clonedTokens.find(
+    (token) => token.config.symbol.toLowerCase() === symbol.toLowerCase()
+  );
+}