solforge 0.2.0 → 0.2.1

package/docs/CONFIGURATION.md

@@ -0,0 +1,407 @@
+# Configuration Guide
+
+This guide covers all configuration options available in SolForge's `sf.config.json` file.
+
+## Configuration File Structure
+
+```json
+{
+  "name": "string",
+  "description": "string (optional)",
+  "tokens": [
+    /* TokenConfig[] */
+  ],
+  "programs": [
+    /* ProgramConfig[] */
+  ],
+  "localnet": {
+    /* LocalnetConfig */
+  }
+}
+```
+
+## Root Configuration
+
+### `name` (required)
+
+- **Type**: `string`
+- **Default**: `"solforge-localnet"`
+- **Description**: Name identifier for your localnet configuration
+
+### `description` (optional)
+
+- **Type**: `string`
+- **Description**: Human-readable description of your setup
+
+### `tokens` (optional)
+
+- **Type**: `TokenConfig[]`
+- **Default**: `[]`
+- **Description**: Array of tokens to clone from mainnet
+
+### `programs` (optional)
+
+- **Type**: `ProgramConfig[]`
+- **Default**: `[]`
+- **Description**: Array of programs to clone from mainnet
+
+### `localnet` (optional)
+
+- **Type**: `LocalnetConfig`
+- **Description**: Validator configuration options
+
+## Token Configuration (`TokenConfig`)
+
+### `symbol` (required)
+
+- **Type**: `string`
+- **Description**: Token symbol (e.g., "USDC", "SOL")
+- **Example**: `"USDC"`
+
+### `mainnetMint` (required)
+
+- **Type**: `string`
+- **Description**: Mainnet mint address to clone
+- **Example**: `"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"`
+
+### `mintAuthority` (optional)
+
+- **Type**: `string`
+- **Description**: Path to keypair file for mint authority
+- **Example**: `"./keypairs/mint-authority.json"`
+- **Note**: If not provided, a new keypair will be generated
+
+### `mintAmount` (optional)
+
+- **Type**: `number`
+- **Default**: `1000000`
+- **Description**: Amount to mint to the mint authority
+- **Note**: Amount is in token's base units (considering decimals)
+
+### `cloneMetadata` (optional)
+
+- **Type**: `boolean`
+- **Default**: `true`
+- **Description**: Whether to clone token metadata from mainnet
+
+### `recipients` (optional)
+
+- **Type**: `RecipientConfig[]`
+- **Default**: `[]`
+- **Description**: List of wallets to receive tokens after minting
+
+#### `RecipientConfig`
+
+```json
+{
+  "wallet": "string (required)",
+  "amount": "number (required)"
+}
+```
+
+- `wallet`: Public key of recipient wallet
+- `amount`: Amount to transfer (in token's base units)
+
+### Example Token Configuration
+
+```json
+{
+  "symbol": "USDC",
+  "mainnetMint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
+  "mintAuthority": "./keypairs/usdc-mint.json",
+  "mintAmount": 10000000000,
+  "cloneMetadata": true,
+  "recipients": [
+    {
+      "wallet": "YourWalletPublicKeyHere",
+      "amount": 1000000000
+    },
+    {
+      "wallet": "AnotherWalletPublicKeyHere",
+      "amount": 500000000
+    }
+  ]
+}
+```
+
+## Program Configuration (`ProgramConfig`)
+
+### `name` (optional)
+
+- **Type**: `string`
+- **Description**: Friendly name for the program
+- **Example**: `"Jupiter Aggregator"`
+
+### `mainnetProgramId` (required)
+
+- **Type**: `string`
+- **Description**: Mainnet program ID to clone
+- **Example**: `"JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4"`
+
+### `deployPath` (optional)
+
+- **Type**: `string`
+- **Description**: Path to local .so file to deploy instead of cloning
+- **Example**: `"./target/deploy/my_program.so"`
+
+### `upgradeable` (optional)
+
+- **Type**: `boolean`
+- **Default**: `false`
+- **Description**: Whether the program should be deployed as upgradeable
+
+### `cluster` (optional)
+
+- **Type**: `"mainnet-beta" | "devnet" | "testnet"`
+- **Default**: `"mainnet-beta"`
+- **Description**: Source cluster to clone the program from
+
+### `dependencies` (optional)
+
+- **Type**: `string[]`
+- **Default**: `[]`
+- **Description**: Array of program IDs this program depends on
+- **Note**: Dependencies will be deployed before this program
+
+### Example Program Configuration
+
+```json
+{
+  "name": "Jupiter Aggregator",
+  "mainnetProgramId": "JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4",
+  "cluster": "mainnet-beta",
+  "upgradeable": false,
+  "dependencies": ["TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"]
+}
+```
+
+## Localnet Configuration (`LocalnetConfig`)
+
+### `airdropAmount` (optional)
+
+- **Type**: `number`
+- **Default**: `100`
+- **Description**: SOL amount for initial airdrops
+- **Unit**: SOL
+
+### `faucetAccounts` (optional)
+
+- **Type**: `string[]`
+- **Default**: `[]`
+- **Description**: Public keys to receive initial SOL airdrops
+
+### `port` (optional)
+
+- **Type**: `number`
+- **Default**: `8899`
+- **Range**: `1000-65535`
+- **Description**: RPC port for the validator
+
+### `faucetPort` (optional)
+
+- **Type**: `number`
+- **Default**: `9900`
+- **Range**: `1000-65535`
+- **Description**: Faucet port for the validator
+
+### `reset` (optional)
+
+- **Type**: `boolean`
+- **Default**: `false`
+- **Description**: Whether to reset the ledger on startup
+
+### `logLevel` (optional)
+
+- **Type**: `"trace" | "debug" | "info" | "warn" | "error"`
+- **Default**: `"info"`
+- **Description**: Validator log level
+
+### `quiet` (optional)
+
+- **Type**: `boolean`
+- **Default**: `false`
+- **Description**: Suppress validator output
+
+### `ledgerPath` (optional)
+
+- **Type**: `string`
+- **Description**: Custom path for ledger data
+- **Note**: If not specified, uses default location
+
+### `bindAddress` (optional)
+
+- **Type**: `string`
+- **Default**: `"127.0.0.1"`
+- **Description**: IP address to bind the validator to
+
+### `limitLedgerSize` (optional)
+
+- **Type**: `number`
+- **Default**: `100000`
+- **Description**: Maximum ledger size in slots
+
+### `rpc` (optional)
+
+- **Type**: `string` (URL)
+- **Default**: `"https://api.mainnet-beta.solana.com"`
+- **Description**: RPC URL for cloning data from mainnet
+
+### Example Localnet Configuration
+
+```json
+{
+  "airdropAmount": 1000,
+  "faucetAccounts": ["YourWalletPublicKeyHere", "AnotherWalletPublicKeyHere"],
+  "port": 8899,
+  "faucetPort": 9900,
+  "reset": false,
+  "logLevel": "debug",
+  "quiet": false,
+  "bindAddress": "0.0.0.0",
+  "limitLedgerSize": 50000,
+  "rpc": "https://mainnet.helius-rpc.com/?api-key=your-key"
+}
+```
+
+## Complete Example Configuration
+
+```json
+{
+  "name": "defi-development",
+  "description": "DeFi development environment with popular tokens and DEX programs",
+  "tokens": [
+    {
+      "symbol": "USDC",
+      "mainnetMint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
+      "mintAmount": 10000000000,
+      "cloneMetadata": true,
+      "recipients": [
+        {
+          "wallet": "YourWalletPublicKeyHere",
+          "amount": 1000000000
+        }
+      ]
+    },
+    {
+      "symbol": "USDT",
+      "mainnetMint": "Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB",
+      "mintAmount": 10000000000,
+      "cloneMetadata": true,
+      "recipients": [
+        {
+          "wallet": "YourWalletPublicKeyHere",
+          "amount": 1000000000
+        }
+      ]
+    }
+  ],
+  "programs": [
+    {
+      "name": "Jupiter Aggregator",
+      "mainnetProgramId": "JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4",
+      "cluster": "mainnet-beta"
+    },
+    {
+      "name": "Orca",
+      "mainnetProgramId": "9W959DqEETiGZocYWCQPaJ6sBmUzgfxXfqGeTEdp3aQP",
+      "cluster": "mainnet-beta"
+    },
+    {
+      "name": "Token Metadata",
+      "mainnetProgramId": "metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s",
+      "cluster": "mainnet-beta"
+    }
+  ],
+  "localnet": {
+    "airdropAmount": 1000,
+    "faucetAccounts": ["YourWalletPublicKeyHere"],
+    "port": 8899,
+    "faucetPort": 9900,
+    "reset": false,
+    "logLevel": "info",
+    "bindAddress": "127.0.0.1",
+    "limitLedgerSize": 100000,
+    "rpc": "https://api.mainnet-beta.solana.com"
+  }
+}
+```
+
+## Configuration Validation
+
+SolForge validates your configuration file using Zod schemas. Common validation errors:
+
+### Invalid Token Configuration
+
+```
+❌ Token symbol is required
+❌ Mainnet mint address is required
+❌ Mint amount must be positive
+❌ Wallet address is required for recipients
+```
+
+### Invalid Program Configuration
+
+```
+❌ Program ID is required
+❌ Invalid cluster (must be mainnet-beta, devnet, or testnet)
+```
+
+### Invalid Localnet Configuration
+
+```
+❌ Port must be between 1000 and 65535
+❌ RPC must be a valid URL
+❌ Log level must be one of: trace, debug, info, warn, error
+```
+
+## Best Practices
+
+1. **Use descriptive names**: Make your configuration name and description clear
+2. **Start small**: Begin with a few tokens/programs and add more as needed
+3. **Use custom RPC**: Consider using a dedicated RPC endpoint for better performance
+4. **Manage keypairs**: Store mint authority keypairs securely
+5. **Port management**: Use different ports for multiple environments
+6. **Reset wisely**: Use `reset: true` for clean starts, `false` for persistent data
+7. **Log levels**: Use `debug` for development, `info` for production
+
+## Environment-Specific Configurations
+
+### Development Environment
+
+```json
+{
+  "name": "dev-environment",
+  "localnet": {
+    "reset": true,
+    "logLevel": "debug",
+    "airdropAmount": 1000
+  }
+}
+```
+
+### Testing Environment
+
+```json
+{
+  "name": "test-environment",
+  "localnet": {
+    "reset": false,
+    "logLevel": "warn",
+    "quiet": true
+  }
+}
+```
+
+### Production-like Environment
+
+```json
+{
+  "name": "prod-like-environment",
+  "localnet": {
+    "reset": false,
+    "logLevel": "error",
+    "limitLedgerSize": 1000000,
+    "rpc": "https://your-premium-rpc-endpoint.com"
+  }
+}
+```

package/package.json

@@ -1,47 +1,58 @@
 {
-	"name": "solforge",
-	"version": "0.2.0",
-	"module": "index.ts",
-	"type": "module",
-	"private": false,
-	"scripts": {
-		"lint": "biome check",
-		"cli": "bun src/cli/main.ts",
-		"build:gui": "bun build src/gui/src/main.tsx --outdir src/gui/public/build --target=browser --minify",
-		"build:css": "bunx tailwindcss -i src/gui/src/index.css -o src/gui/public/app.css --minify",
-		"build": "bun run build:bin",
-		"build:bin": "bun run build:css && bun run build:gui && bun build --compile src/cli/main.ts --outfile dist/solforge",
-		"build:bin:darwin-arm64": "bun run build:css && bun run build:gui && bun build --compile --target=bun-darwin-arm64 src/cli/main.ts --outfile dist/solforge-darwin-arm64",
-		"build:bin:darwin-x64": "bun run build:css && bun run build:gui && bun build --compile --target=bun-darwin-x64 src/cli/main.ts --outfile dist/solforge-darwin-x64",
-		"build:bin:linux-x64": "bun run build:css && bun run build:gui && bun build --compile --target=bun-linux-x64 src/cli/main.ts --outfile dist/solforge-linux-x64",
-		"build:bin:linux-arm64": "bun run build:css && bun run build:gui && bun build --compile --target=bun-linux-arm64 src/cli/main.ts --outfile dist/solforge-linux-arm64",
-		"build:bin:windows-x64": "bun run build:css && bun run build:gui && bun build --compile --target=bun-windows-x64 src/cli/main.ts --outfile dist/solforge-windows-x64.exe",
-		"build:bin:all": "bun run build:bin:darwin-arm64 && bun run build:bin:darwin-x64 && bun run build:bin:linux-x64 && bun run build:bin:linux-arm64 && bun run build:bin:windows-x64"
-	},
-	"devDependencies": {
-		"@biomejs/biome": "2.2.4",
-		"@types/bun": "latest",
-		"@types/react": "^19.1.13",
-		"@types/react-dom": "^19.1.9",
-		"autoprefixer": "^10.4.21",
-		"drizzle-kit": "^0.31.4",
-		"postcss": "^8.5.6",
-		"tailwindcss": "3"
-	},
-	"peerDependencies": {
-		"typescript": "^5"
-	},
-	"dependencies": {
-		"@clack/prompts": "^0.11.0",
-		"@solana-program/compute-budget": "^0.9.0",
-		"@solana-program/memo": "^0.8.0",
-		"@solana-program/system": "^0.8.0",
-		"@solana-program/token": "^0.6.0",
-		"@solana/kit": "^3.0.3",
-		"@solana/spl-token": "^0.4.14",
-		"drizzle-orm": "^0.44.5",
-		"litesvm": "^0.3.3",
-		"react": "^19.1.1",
-		"react-dom": "^19.1.1"
-	}
+  "name": "solforge",
+  "version": "0.2.1",
+  "module": "index.ts",
+  "type": "module",
+  "private": false,
+  "bin": {
+    "solforge": "dist/solforge"
+  },
+  "files": [
+    "dist",
+    "src",
+    "server",
+    "docs",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "lint": "biome check",
+    "cli": "bun src/cli/main.ts",
+    "build:gui": "bun build src/gui/src/main.tsx --outdir src/gui/public/build --target=browser --minify",
+    "build:css": "bunx tailwindcss -i src/gui/src/index.css -o src/gui/public/app.css --minify",
+    "build": "bun run build:bin",
+    "build:bin": "bun run build:css && bun run build:gui && bun build --compile src/cli/main.ts --outfile dist/solforge",
+    "build:bin:darwin-arm64": "bun run build:css && bun run build:gui && bun build --compile --target=bun-darwin-arm64 src/cli/main.ts --outfile dist/solforge-darwin-arm64",
+    "build:bin:darwin-x64": "bun run build:css && bun run build:gui && bun build --compile --target=bun-darwin-x64 src/cli/main.ts --outfile dist/solforge-darwin-x64",
+    "build:bin:linux-x64": "bun run build:css && bun run build:gui && bun build --compile --target=bun-linux-x64 src/cli/main.ts --outfile dist/solforge-linux-x64",
+    "build:bin:linux-arm64": "bun run build:css && bun run build:gui && bun build --compile --target=bun-linux-arm64 src/cli/main.ts --outfile dist/solforge-linux-arm64",
+    "build:bin:windows-x64": "bun run build:css && bun run build:gui && bun build --compile --target=bun-windows-x64 src/cli/main.ts --outfile dist/solforge-windows-x64.exe",
+    "build:bin:all": "bun run build:bin:darwin-arm64 && bun run build:bin:darwin-x64 && bun run build:bin:linux-x64 && bun run build:bin:linux-arm64 && bun run build:bin:windows-x64"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.2.4",
+    "@types/bun": "latest",
+    "@types/react": "^19.1.13",
+    "@types/react-dom": "^19.1.9",
+    "autoprefixer": "^10.4.21",
+    "drizzle-kit": "^0.31.4",
+    "postcss": "^8.5.6",
+    "tailwindcss": "3"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.11.0",
+    "@solana-program/compute-budget": "^0.9.0",
+    "@solana-program/memo": "^0.8.0",
+    "@solana-program/system": "^0.8.0",
+    "@solana-program/token": "^0.6.0",
+    "@solana/kit": "^3.0.3",
+    "@solana/spl-token": "^0.4.14",
+    "drizzle-orm": "^0.44.5",
+    "litesvm": "^0.3.3",
+    "react": "^19.1.1",
+    "react-dom": "^19.1.1"
+  }
 }

package/src/api-server-entry.ts

@@ -0,0 +1,109 @@
+#!/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 hostIndex = args.indexOf("--host");
+    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> [--host <host>]"
+      );
+      process.exit(1);
+    }
+
+    const port = parseInt(args[portIndex + 1]!);
+    const host =
+      hostIndex !== -1 && args[hostIndex + 1] ? args[hostIndex + 1] : undefined;
+    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,
+      host,
+      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);
+});