solforge 0.1.7 → 0.2.0

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";

package/server/methods/account/parsers/index.ts

@@ -0,0 +1,52 @@
+import { PublicKey } from "@solana/web3.js";
+import type { RpcMethodContext } from "../../../server/types";
+import { parseUpgradeableLoader } from "./loader-upgradeable";
+import { parseSplTokenAccountOrMint } from "./spl-token";
+import { parseSystemAccount } from "./system";
+
+export type ParsedAccountData = {
+	program: string;
+	parsed: any; // match Solana RPC jsonParsed payloads
+	space: number;
+} | null;
+
+export function parseAccountJson(
+	pubkey: PublicKey,
+	account: {
+		owner: PublicKey | string;
+		data: Uint8Array | Buffer | number[];
+		lamports: bigint | number;
+		executable?: boolean;
+		rentEpoch?: bigint | number;
+	},
+	context: RpcMethodContext,
+): ParsedAccountData {
+	const ownerStr =
+		typeof account.owner === "string"
+			? account.owner
+			: new PublicKey(account.owner).toBase58();
+	const ownerPk =
+		typeof account.owner === "string"
+			? new PublicKey(account.owner)
+			: (account.owner as PublicKey);
+	const dataBytes =
+		account.data instanceof Uint8Array
+			? account.data
+			: Buffer.from(account.data as any);
+	const space = dataBytes.length;
+
+	// 1) System program
+	const sys = parseSystemAccount(ownerStr, space);
+	if (sys) return sys;
+
+	// 2) SPL Token (v1) & Token-2022
+	const token = parseSplTokenAccountOrMint(pubkey, ownerPk, dataBytes, context);
+	if (token) return token;
+
+	// 3) BPF Upgradeable Loader
+	const loader = parseUpgradeableLoader(ownerStr, dataBytes, context);
+	if (loader) return loader;
+
+	// 4) Unknown
+	return { program: "unknown", parsed: null, space };
+}

package/server/methods/account/parsers/loader-upgradeable.ts

@@ -0,0 +1,66 @@
+import { PublicKey } from "@solana/web3.js";
+import type { RpcMethodContext } from "../../../server/types";
+
+const LOADER_UPGRADEABLE = "BPFLoaderUpgradeab1e11111111111111111111111";
+
+export function parseUpgradeableLoader(
+	owner: string,
+	data: Uint8Array,
+	context: RpcMethodContext,
+) {
+	if (owner !== LOADER_UPGRADEABLE) return null;
+	const bytes = data;
+	const dv = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+	const space = bytes.length;
+	let parsed: any = null;
+	try {
+		if (bytes.length >= 4) {
+			const tag = dv.getUint32(0, true);
+			if (tag === 2 && bytes.length >= 36) {
+				// Program: [u32 tag][32 programDataPubkey]
+				const pd = new PublicKey(bytes.slice(4, 36)).toBase58();
+				parsed = { type: "program", info: { programData: pd } };
+			} else if (tag === 3 && bytes.length >= 4 + 8 + 1) {
+				// ProgramData: [u32 tag][u64 slot][Option<Pubkey> upgradeAuthority]
+				const slot = Number(dv.getBigUint64(4, true));
+				let upgradeAuthority: string | null = null;
+				const opt = dv.getUint8(12);
+				let hdr = 13; // after u8 option
+				if (opt === 1 && bytes.length >= 13 + 32) {
+					upgradeAuthority = new PublicKey(bytes.slice(13, 45)).toBase58();
+					hdr = 45;
+				} else if (opt === 0) {
+					hdr = 13;
+				} else if (bytes.length >= 12 + 4) {
+					// Fallback u32 option at offset 12
+					const opt32 = dv.getUint32(12, true);
+					hdr = 16;
+					if (opt32 === 1 && bytes.length >= 16 + 32) {
+						upgradeAuthority = new PublicKey(bytes.slice(16, 48)).toBase58();
+						hdr = 48;
+					}
+				}
+				const programBytes = bytes.slice(hdr);
+				parsed = {
+					type: "programData",
+					info: {
+						slot: slot === 0 ? Number(context.slot) : slot,
+						upgradeAuthority,
+						authority: upgradeAuthority,
+						data: [Buffer.from(programBytes).toString("base64"), "base64"],
+					},
+				};
+			} else if (tag === 1) {
+				// Buffer: [u32 tag][Option<Pubkey> authority]
+				let authority: string | null = null;
+				if (bytes.length >= 5) {
+					const hasAuth = dv.getUint8(4);
+					if (hasAuth === 1 && bytes.length >= 5 + 32)
+						authority = new PublicKey(bytes.slice(5, 37)).toBase58();
+				}
+				parsed = { type: "buffer", info: { authority } };
+			}
+		}
+	} catch {}
+	return { program: "bpf-upgradeable-loader", parsed, space };
+}