solforge 0.1.7 → 0.2.1

package/package.json

@@ -1,71 +1,58 @@
 {
   "name": "solforge",
-  "version": "0.1.7",
-  "description": "Solana localnet orchestration tool for cloning mainnet programs and tokens",
+  "version": "0.2.1",
   "module": "index.ts",
   "type": "module",
   "private": false,
   "bin": {
-    "solforge": "./bin/solforge"
+    "solforge": "dist/solforge"
   },
   "files": [
-    "src/",
-    "scripts/",
-    "tsconfig.json",
-    "bin/",
+    "dist",
+    "src",
+    "server",
+    "docs",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
-    "dev": "bun run --watch src/index.ts",
-    "build": "bun build src/index.ts --outdir ./dist --target bun",
-    "build:binary": "bun build src/index.ts --compile --outfile ./dist/solforge",
-    "build:npm": "mkdir -p bin && bun build src/index.ts --compile --outfile ./bin/solforge",
-    "install:binary": "mkdir -p ~/.local/bin && cp ./dist/solforge ~/.local/bin/solforge && chmod +x ~/.local/bin/solforge",
-    "build:install": "bun run build:binary && bun run install:binary",
-    "postinstall": "node scripts/postinstall.cjs",
-    "prepublishOnly": "rm -rf bin/",
-    "start": "bun run dist/index.js",
-    "test": "bun test",
-    "lint": "bunx @biomejs/biome check src/",
-    "format": "bunx @biomejs/biome format src/ --write"
-  },
-  "dependencies": {
-    "@inquirer/prompts": "^7.5.3",
-    "@solana/spl-token": "^0.4.1",
-    "@solana/web3.js": "^1.87.6",
-    "chalk": "^5.3.0",
-    "commander": "^11.1.0",
-    "cors": "^2.8.5",
-    "express": "^4.18.2",
-    "inquirer": "^9.2.12",
-    "ora": "^8.0.1",
-    "ws": "^8.16.0",
-    "zod": "^3.22.4"
+    "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/node": "^20.10.6",
-    "@types/express": "^4.17.21",
-    "@types/cors": "^2.8.17",
-    "@types/ws": "^8.5.10",
-    "@types/inquirer": "^9.0.7",
-    "@biomejs/biome": "^1.4.1"
+    "@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"
   },
-  "keywords": [
-    "solana",
-    "localnet",
-    "blockchain",
-    "development",
-    "tooling"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/nitishxyz/solforge.git"
-  },
-  "author": "nitishxyz",
-  "license": "MIT"
+  "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/server/index.ts

@@ -0,0 +1,5 @@
+export * from "./methods";
+export { rpcMethods } from "./methods";
+export { createLiteSVMRpcServer, LiteSVMRpcServer } from "./rpc-server";
+export * from "./types";
+export { createLiteSVMWebSocketServer } from "./ws-server";

package/server/lib/base58.ts

@@ -0,0 +1,33 @@
+const ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+const BASE = BigInt(ALPHABET.length);
+
+export function encodeBase58(bytes: Uint8Array): string {
+	let num = 0n;
+	for (let i = 0; i < bytes.length; i++)
+		num = num * 256n + BigInt(bytes[i] || 0);
+	let encoded = "";
+	while (num > 0n) {
+		const remainder = num % BASE;
+		num = num / BASE;
+		encoded = ALPHABET[Number(remainder)] + encoded;
+	}
+	for (let i = 0; i < bytes.length && bytes[i] === 0; i++)
+		encoded = "1" + encoded;
+	return encoded || "1";
+}
+
+export function decodeBase58(str: string): Uint8Array {
+	let num = 0n;
+	for (const char of str) {
+		const index = ALPHABET.indexOf(char);
+		if (index === -1) throw new Error("Invalid base58 character");
+		num = num * BASE + BigInt(index);
+	}
+	const bytes: number[] = [];
+	while (num > 0n) {
+		bytes.unshift(Number(num % 256n));
+		num = num / 256n;
+	}
+	for (let i = 0; i < str.length && str[i] === "1"; i++) bytes.unshift(0);
+	return new Uint8Array(bytes.length > 0 ? bytes : [0]);
+}

package/server/lib/faucet.ts

@@ -0,0 +1,110 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import {
+	Keypair,
+	type PublicKey,
+	SystemProgram,
+	Transaction,
+} from "@solana/web3.js";
+import type { LiteSVM } from "litesvm";
+
+const DEFAULT_PATH =
+	process.env.SOLFORGE_FAUCET_PATH || ".solforge/faucet.json";
+// Default to 1,000,000 SOL so we never run out in local dev.
+// Override with SOLFORGE_FAUCET_LAMPORTS if desired.
+const DEFAULT_INITIAL_LAMPORTS = BigInt(
+	process.env.SOLFORGE_FAUCET_LAMPORTS || "1000000000000000",
+); // 1e15 lamports = 1,000,000 SOL
+
+type FaucetFile = { secretKey: string; publicKey: string; createdAt: string };
+
+function ensureDir(path: string) {
+	try {
+		mkdirSync(dirname(path), { recursive: true });
+	} catch {}
+}
+
+export function loadOrCreateFaucet(path: string = DEFAULT_PATH): Keypair {
+	try {
+		if (existsSync(path)) {
+			const raw = readFileSync(path, "utf8");
+			const data = JSON.parse(raw) as FaucetFile;
+			const secret = Buffer.from(data.secretKey, "base64");
+			return Keypair.fromSecretKey(new Uint8Array(secret));
+		}
+	} catch {}
+
+	const kp = Keypair.generate();
+	try {
+		ensureDir(path);
+		const payload: FaucetFile = {
+			secretKey: Buffer.from(kp.secretKey).toString("base64"),
+			publicKey: kp.publicKey.toBase58(),
+			createdAt: new Date().toISOString(),
+		};
+		writeFileSync(path, JSON.stringify(payload, null, 2), "utf8");
+	} catch {}
+	return kp;
+}
+
+export function fundFaucetIfNeeded(
+	svm: LiteSVM,
+	faucet: Keypair,
+	targetLamports: bigint = DEFAULT_INITIAL_LAMPORTS,
+): bigint {
+	let bal = 0n;
+	try {
+		bal = svm.getBalance(faucet.publicKey as PublicKey) || 0n;
+	} catch {
+		bal = 0n;
+	}
+	if (bal >= targetLamports) return bal;
+
+	// Observed per-account airdrop cap ~10k SOL. Work around by creating feeder accounts,
+	// airdropping to each, then transferring to the faucet until the target is reached.
+	const LAMPORTS_PER_SOL = 1_000_000_000n;
+	const PER_ACCOUNT_CAP = 10_000n * LAMPORTS_PER_SOL; // 10k SOL per feeder
+	const FEE = 5_000n; // rough fee for legacy transfer
+
+	let remaining = targetLamports - bal;
+	let safety = 0;
+	while (remaining > 0n && safety < 1000) {
+		safety++;
+		const feeder = Keypair.generate();
+		const mint = remaining > PER_ACCOUNT_CAP ? PER_ACCOUNT_CAP : remaining;
+		// Airdrop enough to cover transfer + fee
+		try {
+			svm.airdrop(feeder.publicKey as PublicKey, mint + FEE);
+		} catch {
+			// If airdrop fails, try smaller amount; if still fails, stop
+			try {
+				svm.airdrop(feeder.publicKey as PublicKey, 1_000_000_000n);
+			} catch {
+				break;
+			}
+		}
+
+		// Transfer from feeder -> faucet
+		try {
+			const tx = new Transaction();
+			try {
+				tx.recentBlockhash = svm.latestBlockhash();
+			} catch {}
+			tx.add(
+				SystemProgram.transfer({
+					fromPubkey: feeder.publicKey,
+					toPubkey: faucet.publicKey as PublicKey,
+					lamports: Number(mint),
+				}),
+			);
+			tx.sign(feeder);
+			svm.sendTransaction(tx);
+			remaining -= mint;
+		} catch {}
+	}
+
+	try {
+		bal = svm.getBalance(faucet.publicKey as PublicKey) || 0n;
+	} catch {}
+	return bal;
+}

package/server/lib/spl-token.ts

@@ -0,0 +1,57 @@
+import { PublicKey } from "@solana/web3.js";
+
+export const TOKEN_PROGRAM_ID = new PublicKey(
+	"TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
+);
+
+// Minimal SPL Token v1 layouts
+export type DecodedMint = {
+	supply: bigint;
+	decimals: number;
+	isInitialized: boolean;
+};
+
+export type DecodedTokenAccount = {
+	mint: string;
+	owner: string;
+	amount: bigint;
+	state: number;
+	delegatedAmount: bigint;
+};
+
+export function decodeMint(data: Uint8Array): DecodedMint | null {
+	if (!data || data.length < 82) return null;
+	const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+	// supply at offset 36? Common layout: 4 (opt) + 32 (auth) + 8 (supply) + 1 (dec) + 1 (init)
+	const supply = view.getBigUint64(36, true);
+	const decimals = view.getUint8(44);
+	const isInitialized = view.getUint8(45) !== 0;
+	return { supply, decimals, isInitialized };
+}
+
+export function decodeTokenAccount(
+	data: Uint8Array,
+): DecodedTokenAccount | null {
+	if (!data || data.length < 165) return null;
+	const mint = new PublicKey(data.slice(0, 32)).toBase58();
+	const owner = new PublicKey(data.slice(32, 64)).toBase58();
+	const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+	const amount = view.getBigUint64(64, true);
+	const state = data[108];
+	const delegatedAmount = view.getBigUint64(124, true);
+	return { mint, owner, amount, state, delegatedAmount };
+}
+
+export function formatUiAmount(amount: bigint, decimals: number) {
+	const base = BigInt(10) ** BigInt(decimals);
+	const whole = amount / base;
+	const frac = amount % base;
+	const fracStr = frac.toString().padStart(decimals, "0").replace(/0+$/, "");
+	const ui = fracStr.length > 0 ? `${whole}.${fracStr}` : `${whole}`;
+	return {
+		amount: amount.toString(),
+		decimals,
+		uiAmount: Number(ui),
+		uiAmountString: ui,
+	};
+}

package/server/methods/TEMPLATE.md

@@ -0,0 +1,117 @@
+# RPC Method Template
+
+Use this template when adding new RPC methods to SolForge.
+
+## File Template
+
+```typescript
+import { PublicKey } from "@solana/web3.js"; // Only if needed
+import type { RpcMethodHandler } from "../types"; // Adjust path based on location
+
+/**
+ * Implements the methodName RPC method
+ * @see https://docs.solana.com/api/http#methodname
+ */
+export const methodName: RpcMethodHandler = (id, params, context) => {
+  // 1. Parse parameters
+  const [param1, param2, config] = params;
+  
+  // 2. Validate parameters (if needed)
+  if (!param1) {
+    return context.createErrorResponse(
+      id,
+      -32602,
+      "Missing required parameter: param1"
+    );
+  }
+  
+  try {
+    // 3. Execute the RPC logic
+    const result = context.svm.someOperation();
+    
+    // 4. Format and return the response
+    return context.createSuccessResponse(id, {
+      context: { 
+        slot: Number(context.slot),
+        apiVersion: "1.18.0" // If needed
+      },
+      value: result
+    });
+  } catch (error: any) {
+    // 5. Handle errors appropriately
+    return context.createErrorResponse(
+      id,
+      -32603, // Use appropriate error code
+      "Operation failed",
+      error.message
+    );
+  }
+};
+```
+
+## Common Patterns
+
+### Methods that modify state
+```typescript
+// After successful operation, increment slot/blockHeight
+if (success) {
+  // This is handled in the main server now
+  // Just return success response
+  return context.createSuccessResponse(id, signature);
+}
+```
+
+### Methods with optional config
+```typescript
+const [address, config] = params;
+const encoding = config?.encoding || "base64";
+const commitment = config?.commitment || "confirmed";
+```
+
+### Batch operations
+```typescript
+const results = addresses.map(addr => {
+  try {
+    // Process each item
+    return processItem(addr);
+  } catch {
+    // Return null for failed items
+    return null;
+  }
+});
+```
+
+## Error Codes Reference
+
+- `-32700`: Parse error (JSON parsing failed)
+- `-32600`: Invalid request (not a valid JSON-RPC request)
+- `-32601`: Method not found
+- `-32602`: Invalid params
+- `-32603`: Internal error
+- `-32000`: Generic server error
+- `-32001`: Resource not found
+- `-32002`: Resource unavailable
+- `-32003`: Transaction rejected
+- `-32004`: Method not supported
+- `-32005`: Limit exceeded
+
+## Checklist
+
+Before committing a new RPC method:
+
+- [ ] Method follows naming convention (camelCase)
+- [ ] File uses kebab-case naming
+- [ ] Proper TypeScript types used
+- [ ] Error handling implemented
+- [ ] Success case tested
+- [ ] Error cases tested
+- [ ] Added to methods/index.ts
+- [ ] Documentation updated in README.md
+- [ ] Follows SolForge patterns
+
+## Examples in Codebase
+
+- Simple query: See `get-balance.ts`
+- Complex response: See `get-account-info.ts`
+- Transaction handling: See `send-transaction.ts`
+- Batch operation: See `get-multiple-accounts.ts`

package/server/methods/account/get-account-info.ts

@@ -0,0 +1,90 @@
+import { PublicKey } from "@solana/web3.js";
+import type { RpcMethodHandler } from "../../types";
+import { parseAccountJson } from "./parsers";
+
+/**
+ * Implements the getAccountInfo RPC method
+ * @see https://docs.solana.com/api/http#getaccountinfo
+ */
+export const getAccountInfo: RpcMethodHandler = async (id, params, context) => {
+	const [pubkeyStr, config] = params;
+	const encoding = config?.encoding || "base64";
+
+	try {
+		const pubkey = new PublicKey(pubkeyStr);
+		const account = context.svm.getAccount(pubkey);
+
+		if (!account) {
+			return context.createSuccessResponse(id, {
+				context: { slot: Number(context.slot) },
+				value: null,
+			});
+		}
+
+		const owner = new PublicKey(account.owner).toBase58();
+		// Opportunistic index update
+		try {
+			await context.store?.upsertAccounts([
+				{
+					address: pubkey.toBase58(),
+					lamports: Number(account.lamports || 0n),
+					ownerProgram: owner,
+					executable: !!account.executable,
+					rentEpoch: Number(account.rentEpoch || 0),
+					dataLen: account.data?.length ?? 0,
+					dataBase64: undefined,
+					lastSlot: Number(context.slot),
+				},
+			]);
+		} catch {}
+
+		if (encoding === "jsonParsed") {
+			const parsed = parseAccountJson(
+				pubkey,
+				{
+					owner: new PublicKey(account.owner),
+					data: account.data ? new Uint8Array(account.data) : new Uint8Array(),
+					lamports: account.lamports,
+					executable: account.executable,
+					rentEpoch: account.rentEpoch,
+				},
+				context,
+			);
+
+			return context.createSuccessResponse(id, {
+				context: { slot: Number(context.slot) },
+				value: {
+					lamports: Number(account.lamports),
+					owner,
+					executable: account.executable,
+					rentEpoch: Number(account.rentEpoch || 0),
+					data: parsed || {
+						program: "unknown",
+						parsed: null,
+						space: account.data?.length ?? 0,
+					},
+				},
+			});
+		}
+
+		const accountInfo = {
+			lamports: Number(account.lamports),
+			owner,
+			data: [Buffer.from(account.data).toString("base64"), "base64"] as const,
+			executable: account.executable,
+			rentEpoch: Number(account.rentEpoch || 0),
+		};
+
+		return context.createSuccessResponse(id, {
+			context: { slot: Number(context.slot) },
+			value: accountInfo,
+		});
+	} catch (error: any) {
+		return context.createErrorResponse(
+			id,
+			-32602,
+			"Invalid params",
+			error.message,
+		);
+	}
+};

package/server/methods/account/get-balance.ts

@@ -0,0 +1,27 @@
+import { PublicKey } from "@solana/web3.js";
+import type { RpcMethodHandler } from "../../types";
+
+/**
+ * Implements the getBalance RPC method
+ * @see https://docs.solana.com/api/http#getbalance
+ */
+export const getBalance: RpcMethodHandler = (id, params, context) => {
+	const [pubkeyStr] = params;
+
+	try {
+		const pubkey = new PublicKey(pubkeyStr);
+		const balance = context.svm.getBalance(pubkey);
+
+		return context.createSuccessResponse(id, {
+			context: { slot: Number(context.slot) },
+			value: Number(balance || 0n),
+		});
+	} catch (error: any) {
+		return context.createErrorResponse(
+			id,
+			-32602,
+			"Invalid params",
+			error.message,
+		);
+	}
+};

package/server/methods/account/get-multiple-accounts.ts

@@ -0,0 +1,83 @@
+import { PublicKey } from "@solana/web3.js";
+import type { RpcMethodHandler } from "../../types";
+
+/**
+ * Implements the getMultipleAccounts RPC method
+ * @see https://docs.solana.com/api/http#getmultipleaccounts
+ */
+export const getMultipleAccounts: RpcMethodHandler = async (
+	id,
+	params,
+	context,
+) => {
+	const [pubkeys, config] = params;
+	const encoding = config?.encoding || "base64";
+
+	const accounts = pubkeys.map((pubkeyStr: string) => {
+		try {
+			const pubkey = new PublicKey(pubkeyStr);
+			const account = context.svm.getAccount(pubkey);
+
+			if (!account) {
+				return null;
+			}
+
+			const owner = new PublicKey(account.owner).toBase58();
+			if (encoding === "jsonParsed") {
+				const program =
+					owner === "11111111111111111111111111111111" ? "system" : "unknown";
+				const space = account.data?.length ?? 0;
+				return {
+					lamports: Number(account.lamports),
+					owner,
+					executable: account.executable,
+					rentEpoch: Number(account.rentEpoch || 0),
+					data: {
+						program,
+						parsed: program === "system" ? { type: "account", info: {} } : null,
+						space,
+					},
+				};
+			}
+
+			return {
+				lamports: Number(account.lamports),
+				owner,
+				data: [Buffer.from(account.data).toString("base64"), "base64"] as const,
+				executable: account.executable,
+				rentEpoch: Number(account.rentEpoch || 0),
+			};
+		} catch {
+			return null;
+		}
+	});
+
+	// Opportunistic index update
+	try {
+		const snaps: any[] = [];
+		for (const pubkeyStr of pubkeys) {
+			try {
+				const pubkey = new PublicKey(pubkeyStr);
+				const acc = context.svm.getAccount(pubkey);
+				if (!acc) continue;
+				const owner = new PublicKey(acc.owner).toBase58();
+				snaps.push({
+					address: pubkey.toBase58(),
+					lamports: Number(acc.lamports || 0n),
+					ownerProgram: owner,
+					executable: !!acc.executable,
+					rentEpoch: Number(acc.rentEpoch || 0),
+					dataLen: acc.data?.length ?? 0,
+					dataBase64: undefined,
+					lastSlot: Number(context.slot),
+				});
+			} catch {}
+		}
+		if (snaps.length) await context.store?.upsertAccounts(snaps);
+	} catch {}
+
+	return context.createSuccessResponse(id, {
+		context: { slot: Number(context.slot) },
+		value: accounts,
+	});
+};

package/server/methods/account/get-parsed-account-info.ts

@@ -0,0 +1,21 @@
+import type { RpcMethodHandler } from "../../types";
+import { getAccountInfo } from "./get-account-info";
+
+export const getParsedAccountInfo: RpcMethodHandler = async (
+	id,
+	params,
+	context,
+) => {
+	const [pubkey, config] = params || [];
+	const cfg = { ...(config || {}), encoding: "jsonParsed" };
+	try {
+		return await getAccountInfo(id, [pubkey, cfg], context);
+	} catch (error: any) {
+		return context.createErrorResponse(
+			id,
+			-32603,
+			"Internal error",
+			error.message,
+		);
+	}
+};

package/server/methods/account/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Account-related RPC methods
+ *
+ * This module contains all account-related RPC methods.
+ * Each method is in its own file to maintain modularity.
+ */
+
+export { getAccountInfo } from "./get-account-info";
+export { getBalance } from "./get-balance";
+export { getMultipleAccounts } from "./get-multiple-accounts";
+export { getParsedAccountInfo } from "./get-parsed-account-info";
+export { requestAirdrop } from "./request-airdrop";