solforge 0.1.6 → 0.2.0

package/docs/cli-plan.md

@@ -0,0 +1,154 @@
+# SolForge CLI & GUI Plan
+
+## Goals
+- Ship a single `solforge` CLI with subcommands to manage a local LiteSVM.
+- Provide an optional GUI dashboard (React in Bun) via `solforge gui`.
+- Support a project-local `sf.config.json` for reproducible environments.
+- Add cloning utilities to import programs, program accounts, and tokens from mainnet.
+
+## Command Surface (Phase 1)
+
+- `solforge rpc start [options]` (alias: `solforge start`)
+  - Starts JSON-RPC server and WS server.
+  - Options: `--port <num>` (HTTP), `--ws-port <num>`, `--db-mode <ephemeral|persistent>`, `--db-path <path>`, `--faucet <SOL>`, `--config <path>`.
+  - Reads defaults from `sf.config.json` in CWD when present.
+
+- `solforge gui [options]`
+  - Starts the RPC server and serves a React dashboard via Bun `routes` on the same process.
+  - Options: same as `start`, plus `--ui-port <num>` if served separately (fallback if port sharing is problematic).
+
+- `solforge config init [--force]`
+  - Writes a new `sf.config.json` into CWD with sensible defaults.
+
+- `solforge config get <key>`
+  - Prints value from config (supports dot-path: e.g. `svm.initialLamports`).
+
+- `solforge config set <key> <value>`
+  - Updates config keys (creates nested keys as needed).
+
+- `solforge token clone <mintAddress> [options]`
+  - Clones SPL Token mint and (optionally) selected token accounts from mainnet to LiteSVM.
+  - Options: `--endpoint <url>`, `--all-accounts`, `--holders <N>`, `--program <tokenProgramId>`.
+
+- `solforge program clone <programId> [options]`
+  - Clones an executable program account’s data from mainnet to LiteSVM.
+  - Options: `--endpoint <url>`, `--with-accounts`, `--accounts-limit <N>`, `--filters <json>`.
+
+- `solforge program accounts clone <programId> [options]`
+  - Clones accounts owned by a program from mainnet to LiteSVM (no code).
+  - Options: `--endpoint <url>`, `--limit <N>`, `--filters <json>`.
+
+## Configuration: `sf.config.json`
+
+```json
+{
+  "$schema": "./docs/sf-config.schema.json",
+  "server": {
+    "rpcPort": 8899,
+    "wsPort": 8900,
+    "db": { "mode": "ephemeral", "path": ".solforge/db.db" }
+  },
+  "svm": {
+    "initialLamports": "1000000000000000",
+    "faucetSOL": 1000
+  },
+  "clone": {
+    "endpoint": "https://api.mainnet-beta.solana.com",
+    "programs": ["TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"],
+    "tokens": ["So11111111111111111111111111111111111111112"],
+    "programAccounts": [
+      { "programId": "Tokenkeg...", "limit": 1000, "filters": [] }
+    ]
+  },
+  "gui": {
+    "enabled": false,
+    "uiPath": "ui/public/index.html",
+    "port": null
+  }
+}
+```
+
+Notes:
+- Values like `initialLamports` use string BigInt to avoid JSON precision loss.
+- `clone.endpoint` can be overridden per-command with `--endpoint`.
+
+## Architecture & Files
+
+- `src/cli/`
+  - `main.ts` — CLI entry: parses `Bun.argv`, dispatches subcommands.
+  - `commands/start.ts` — start server from config/flags.
+  - `commands/gui.ts` — start server with UI routes.
+  - `commands/config.ts` — init/get/set helpers.
+  - `commands/token-clone.ts` — clone mint + accounts.
+  - `commands/program-clone.ts` — clone program code.
+  - `commands/program-accounts-clone.ts` — clone owned accounts.
+  - `utils/prompts.ts` — wrapper around `@clack/prompts` for consistent UX.
+
+- `src/config/`
+  - `index.ts` — read/merge/validate config, dot-path get/set, write.
+  - `types.ts` — shared config types.
+
+- `src/rpc/` (facade over current `server/` initially)
+  - `start.ts` — wraps existing RPC/WS start with options: ports, db, gui routes.
+  - Reuse `server/rpc-server.ts` and `server/ws-server.ts` (minimal changes). Later we can move code into `src/rpc/`.
+
+- `ui/`
+  - `public/index.html` — HTML entry (dashboard shell).
+  - `src/app.tsx`, `src/main.tsx`, `src/styles.css` — React app.
+
+## Server Integration for GUI
+
+- Use `Bun.serve({ routes: { "/": indexHtml, ... }, fetch })` so GET `"/"` serves UI while POST continues to handle JSON-RPC.
+- When `gui` is enabled, inject `routes` and optionally set `development: true` when `NODE_ENV !== 'production'`.
+- Fallback: serve UI on separate port if needed via `--ui-port`.
+
+## Cloning Strategy (Phase 1)
+
+- Dependencies: use `@solana/web3.js` or `@solana/kit` for reads only (no new deps).
+- Token clone
+  - Fetch mint account data; create in LiteSVM with same address/data/owner.
+  - Optionally fetch top-N token accounts by balance and recreate.
+- Program clone
+  - Fetch program account; write executable account with original data.
+  - Optional: clone owned program accounts (same flow as program-accounts clone).
+- Program accounts clone
+  - Use `getProgramAccounts` with filters/limit; recreate in LiteSVM.
+
+## Build & Packaging
+
+- Compile `src/cli/main.ts` to single binary: `bun build src/cli/main.ts --compile --outfile dist/solforge`.
+- Drizzle migrations: use the existing `drizzle/` folder. No duplicate embedded SQL.
+  - Packaging options:
+    - A) Distribute binary alongside the `drizzle/` folder (simple; zero duplication).
+    - B) If strict single-file is required, reference the existing SQL files via static imports so Bun bundles them (no duplication), and add a tiny read adapter that feeds them to the migrator. We will only do this if you choose strict single-file.
+
+## Testing (Phase 1)
+
+- `bun:test` unit tests for:
+  - CLI parsing and dispatch.
+  - Config read/write and dot-path set/get.
+  - Start command: start on random port, `/health` responds.
+- Light e2e for cloning commands behind a flag (skipped in CI by default).
+
+## Phases & Milestones
+
+1) CLI Scaffold
+   - CLI entry + help, `rpc start`, `config init|get|set`.
+2) GUI Integration
+   - React scaffold, route via server, `solforge gui` command.
+3) Cloning Utilities
+   - `token clone`, `program clone`, `program accounts clone`.
+4) Polish & Packaging
+   - Build targets, README docs, usage examples.
+
+## Acceptance Criteria (Phase 1)
+
+- `solforge rpc start` (and alias `solforge start`) launches RPC + WS, reading `sf.config.json`.
+- `solforge gui` serves React dashboard and RPC on same process.
+- `solforge config init|get|set` operates on CWD `sf.config.json`.
+- Binaries produced for macOS/Linux/Windows via `bun build --compile`.
+
+## CLI Libraries
+
+- Prompts: `@clack/prompts` from the start for interactive flows (init, confirm, selects).
+- Router: minimal zero-dependency command router over `Bun.argv` for speed and clarity.

package/docs/data-indexing-plan.md

@@ -0,0 +1,214 @@
+# SolForge Data Indexing Plan (Bun + Drizzle ORM + SQLite)
+
+This plan proposes a durable, fast, and simple data indexing layer for SolForge using Bun's native SQLite driver with Drizzle ORM. The goal is to persist and index everything relevant (transactions, accounts, token data, addresses, blocks) so we can power missing RPCs, explorer views, and historical queries that LiteSVM does not natively provide.
+
+## Objectives
+
+- Persist all state-changing events and key reads for durability and queryability.
+- Provide fast lookups for explorer-style methods (e.g., getSignaturesForAddress, getProgramAccounts, token queries).
+- Maintain an in-memory hot cache for the most recent N items while SQLite is the source of truth.
+- Keep the implementation simple and Bun-native: Bun + Drizzle + `bun:sqlite`.
+
+## Tech Choices
+
+- Storage: SQLite (via Bun's `bun:sqlite`) with WAL mode.
+- ORM / schema: Drizzle ORM for schema definition and migrations.
+- Runtime: Single-writer transaction queue; prepared statements for reads.
+- Optional hot cache: Small LRU for last N transactions and frequently accessed accounts.
+
+Reference: https://orm.drizzle.team/docs/connect-bun-sqlite
+
+## High-Level Architecture
+
+- Event-driven ingestion:
+  - On `sendTransaction`/`requestAirdrop`, capture and store full transaction bundle and touch all involved accounts.
+  - On `getAccountInfo`/`getMultipleAccounts`, opportunistically upsert latest account snapshots and update last-seen.
+- Read path:
+  - Explorer calls first check in-memory cache, then fall back to SQLite via Drizzle.
+- Durability:
+  - Store everything important, including raw wire tx (base64), logs, balances, version, and account snapshots.
+
+## Drizzle Schema (SQLite)
+
+- `transactions`
+  - `signature` TEXT PRIMARY KEY
+  - `slot` INTEGER NOT NULL
+  - `block_time` INTEGER NULL
+  - `version` TEXT NOT NULL              // 0 | "legacy"
+  - `err_json` TEXT NULL                 // JSON or null
+  - `fee` INTEGER NOT NULL
+  - `raw_base64` TEXT NOT NULL
+  - `pre_balances_json` TEXT NOT NULL
+  - `post_balances_json` TEXT NOT NULL
+  - `logs_json` TEXT NOT NULL
+  - Index: `slot DESC`
+
+- `tx_accounts`
+  - `signature` TEXT NOT NULL
+  - `account_index` INTEGER NOT NULL
+  - `address` TEXT NOT NULL              // base58
+  - `signer` INTEGER NOT NULL            // 0/1
+  - `writable` INTEGER NOT NULL          // 0/1
+  - `program_id_index` INTEGER NULL
+  - PRIMARY KEY (`signature`, `account_index`)
+  - Indexes: (`address`), (`address`, `signature`) for joins
+
+- `addresses`
+  - `address` TEXT PRIMARY KEY
+  - `first_seen_slot` INTEGER
+  - `last_seen_slot` INTEGER
+  - `type` TEXT NULL                     // "program" | "system" | "user" | "pda" | "token-mint" | "token-account"
+
+- `accounts` (latest snapshot)
+  - `address` TEXT PRIMARY KEY
+  - `lamports` INTEGER NOT NULL
+  - `owner_program` TEXT NOT NULL
+  - `executable` INTEGER NOT NULL
+  - `rent_epoch` INTEGER NOT NULL
+  - `data_len` INTEGER NOT NULL
+  - `data_base64` TEXT NULL              // optional; off by default
+  - `last_slot` INTEGER NOT NULL
+  - Indexes: (`owner_program`), (`last_slot` DESC)
+
+- `account_history` (optional, time-travel)
+  - `address` TEXT NOT NULL
+  - `slot` INTEGER NOT NULL
+  - `lamports` INTEGER
+  - `owner_program` TEXT
+  - `data_len` INTEGER
+  - `data_base64` TEXT NULL
+  - PRIMARY KEY (`address`, `slot`)
+
+- `address_signatures` (fast address → signatures)
+  - `address` TEXT NOT NULL
+  - `signature` TEXT NOT NULL
+  - `slot` INTEGER NOT NULL
+  - `err` INTEGER NOT NULL               // 0/1
+  - `block_time` INTEGER NULL
+  - PRIMARY KEY (`address`, `signature`)
+  - Index: (`address`, `slot` DESC)
+
+- Token normalization
+  - `token_mints`:
+    - `mint` TEXT PRIMARY KEY
+    - `decimals` INTEGER
+    - `supply` TEXT
+    - `mint_authority` TEXT NULL
+    - `freeze_authority` TEXT NULL
+    - `last_slot` INTEGER
+  - `token_accounts`:
+    - `address` TEXT PRIMARY KEY
+    - `mint` TEXT NOT NULL
+    - `owner` TEXT NOT NULL
+    - `amount` TEXT NOT NULL
+    - `delegate` TEXT NULL
+    - `delegated_amount` TEXT NULL
+    - `state` TEXT NOT NULL
+    - `is_native` INTEGER NOT NULL
+    - `last_slot` INTEGER
+  - Indexes: (`owner`), (`mint`)
+
+- `blocks`
+  - `slot` INTEGER PRIMARY KEY
+  - `blockhash` TEXT
+  - `previous_blockhash` TEXT
+  - `parent_slot` INTEGER
+  - `block_time` INTEGER
+
+- `meta_kv`
+  - `key` TEXT PRIMARY KEY
+  - `value` TEXT
+
+Notes:
+- JSON is stored as TEXT in SQLite; parse at the API boundary.
+- Raw transactions stored as base64 TEXT for simplicity.
+
+## PRAGMA and DB Settings
+
+- Execute at startup:
+  - `PRAGMA journal_mode=WAL;`
+  - `PRAGMA synchronous=NORMAL;`
+  - `PRAGMA temp_store=MEMORY;`
+  - `PRAGMA busy_timeout=1000;`
+
+## Ingestion Pipelines
+
+- Transaction ingestion (inside one DB transaction):
+  1. Insert into `transactions` (signature, slot, block_time, version, fee, err_json, raw_base64, pre/post balances, logs).
+  2. Insert into `tx_accounts` (one row per static account key) with signer/writable flags.
+  3. Insert into `address_signatures` for each static account key, joining slot/err.
+  4. For each static account key:
+     - Pull latest account from LiteSVM and upsert into `accounts`.
+     - Upsert into `addresses` (first_seen_slot if new, update last_seen_slot).
+     - If owner is SPL Token program, decode and upsert `token_accounts` / `token_mints`.
+  5. Upsert a `blocks` row tying slot → blockhash/parent_slot/block_time we return via RPC.
+
+- Account read ingestion:
+  - On `getAccountInfo`/`getMultipleAccounts`, upsert snapshot in `accounts` and update `addresses.last_seen_slot`.
+
+## RPC Backed by Store
+
+- `getTransaction` / `getParsedTransaction`:
+  - Memory → SQLite by signature; return structured response (with `version`, `loadedAddresses`).
+- `getSignatureStatuses`:
+  - Memory → SQLite (when `searchTransactionHistory: true`) for slot/err.
+- `getSignaturesForAddress`:
+  - Query `address_signatures` + `transactions` with pagination (before/until/limit) and return explorer-style entries.
+- `getProgramAccounts`:
+  - Query `accounts` filtered by `owner_program` and optional data filters.
+- `getTokenAccountsByOwner` / `getTokenAccountsByDelegate`:
+  - Query `token_accounts` with appropriate filters.
+- `getTokenSupply` / `getTokenLargestAccounts`:
+  - Query `token_mints` and `token_accounts` (by `mint`) with ordering.
+
+## Hot Cache Strategy
+
+- Keep last N transactions and M account snapshots in-memory (LRU); always write-through to SQLite.
+- Memory hits satisfy most recent reads; history and scans go to SQLite.
+
+## Retention & Pruning
+
+- Default: keep all rows (dev/local usage).
+- Optional: environment-controlled retention by time/slot; prune oldest rows in `transactions` and cascade to `tx_accounts` / `address_signatures`.
+
+## Implementation Phases
+
+1. Drizzle bootstrap
+   - Add DB connector (Bun + Drizzle), migrations directory, and PRAGMA setup.
+2. Schema
+   - Implement tables and indexes listed above; generate migrations.
+3. Store module
+   - `TxStore` interface with insert/query helpers; prepared statements; single-writer queue.
+4. Wire into server
+   - Inject store into `RpcMethodContext`; update `recordTransaction` to also persist bundles.
+5. Replace stubs
+   - Implement `getSignaturesForAddress`, `getProgramAccounts`, token endpoints using store.
+6. Opportunistic account refresh
+   - Upsert snapshots on account reads; optional background refresh for hot addresses.
+7. Tests
+   - `bun:test` for ingestion, pagination, filters, and legacy RPC shapes.
+8. Backfill & durability
+   - On boot, import any txs from in-memory records; consider opt-in on-disk WAL retention policy.
+9. Perf tune
+   - Review indexes, batch sizes, and PRAGMAs; add metrics.
+
+## LiteSVM Gaps This Store Covers
+
+- Persistent transaction history across restarts.
+- Address → signature lookups (explorer/UX critical).
+- Program account scans by `owner_program`.
+- SPL Token queries by owner, delegate, and mint.
+- Coherent block/time metadata.
+
+## Open Questions
+
+- Should we store raw account data (`data_base64`) by default? Proposal: off by default, enable via env for debugging.
+- PDA detection: best-effort tagging (cannot always recover seeds deterministically).
+- Future: add richer program parsers (e.g., SPL Token 2022, other common programs) if needed.
+
+## Next Steps (for implementation later)
+
+- Create `storage/tx-store.ts` with Drizzle setup and empty method stubs.
+- Add `context.store` to `RpcMethodContext` and route `recordTransaction` into the store.
+- Land schema/migrations; no behavior change yet.
+

package/docs/gui-roadmap.md

@@ -0,0 +1,202 @@
+# SolForge GUI & Endpoint Plan
+
+## Guiding Principles
+- Ship a single Bun executable that boots both RPC and GUI servers; shared runtime, separate ports (RPC defaults to 8899, GUI to 42069).
+- Keep RPC wide open (same surface as CLI); the GUI talks exclusively to JSON-RPC endpoints.
+- Prefer clarity over cleverness: modular files (<200 LOC) and simple data plumbing per SolForge guidelines.
+- Tailwind-first dark UI: clean, minimal styling with excellent readability.
+- Defer WebSockets; begin with fetch/poll flows and iterate later.
+
+## Deployment Model
+- The executable starts the RPC server on the configured port (default 8899) and, in parallel, starts the GUI server on `guiPort` (default 42069, configurable via setup and `sf.config.json`).
+- Initial setup wizard must surface GUI port alongside RPC/WS ports so users can change it up front.
+- GUI assets are bundled into the executable via Bun HTML import; no external build steps at runtime.
+- Cross-origin is local-only, but to simplify fetches expose a small `/api/*` facade on the GUI server that internally forwards JSON-RPC calls to the RPC port (still RPC-backed, keeps browser code clean).
+
+## Data Strategy (RPC-Only)
+- **Initial Page Load**: GUI fetches programs and tokens immediately after mount; repeat on manual refreshes or via light polling.
+- **Programs**: call `getProgramAccounts`/`getParsedProgramAccounts` with executable filtering to list deployed programs; provide an "Add" call-to-action that links into CLI/docs for cloning.
+- **Tokens/Mints**:
+  - Enumerate known mints with `solforgeListMints` (always available; no admin gating in this phase).
+  - Fetch mint metadata via `getParsedAccountInfo` + SPL decoding for supply/decimals/authority.
+  - Fetch token accounts per mint/owner with `getTokenAccountsByOwner` or parsed variant when needed.
+- **RPC Stats**: gather slot, block height, transaction count, latest blockhash, faucet lamports via core RPC calls.
+- **Airdrop & Mint**: use `requestAirdrop` for SOL, `solforgeMintTo` for SPL tokens; confirmation via `getSignatureStatuses`. Mint UI remains enabled even if `SOLFORGE_ADMIN` is unset (we will revisit restrictions later).
+
+## Backend Tasks
+1. **Server Wiring**
+   - Extend startup (e.g., `startRpcServers`) to spin up the existing RPC server plus a new GUI `Bun.serve` instance listening on `guiPort` (default 42069).
+   - Ensure routes include `/` (HTML import), static assets, and `/api/*` JSON forwarders that call the RPC server internally (using the same process).
+2. **Configuration**
+   - Update config schema, setup wizard, and CLI parsing to persist/read `guiPort` (default 42069) alongside RPC/WS settings.
+   - Document port relationships and how to access both servers.
+3. **Executable Embedding**
+   - Follow `docs/bun-single-file-executable.md`: compile the GUI via HTML import, run Tailwind build prior to `bun build --compile`, ensure assets are in Bun's module graph.
+
+## Frontend Tasks
+1. **Tailwind Setup**
+   - Add Tailwind configuration (dark mode via `class`) and source entry (e.g., `src/gui/src/index.css` with base/utilities/components).
+   - Build CSS to `src/gui/public/tailwind.css`; import from `index.html`.
+2. **App Shell**
+   - Layout with dark background, comfortable spacing, responsive columns.
+   - Place Airdrop/Mint form at top; below it show RPC detail cards; follow with Programs and Tokens sections, each with "Add" actions.
+3. **Airdrop/Mint Form**
+   - Provide select listing `SOL` plus `solforgeListMints` results; capture amount input.
+   - Trigger RPC calls (through `/api/*` or direct JSON-RPC) and display signatures + confirmation status.
+4. **Data Displays**
+   - **RPC Details**: slot, block height, tx count, latest blockhash, faucet balance; auto-refresh every ~5s.
+   - **Programs**: cards/table showing program id, owner, executable flag, data length; include refresh control.
+   - **Tokens**: similar presentation with supply, decimals, mint authority, quick view of holder count.
+5. **Hooks & API**
+   - Implement `src/gui/src/api.ts` with typed helpers for all RPC calls.
+   - Add reusable polling hook to refresh data while keeping components thin (<100 LOC).
+
+## Build & Packaging
+- Tailwind build step (e.g., `bunx tailwindcss -i src/gui/src/index.css -o src/gui/public/tailwind.css --minify`) runs before compiling the executable.
+- Compile the CLI+servers into a single binary: `bun build --compile src/cli/main.ts --outfile dist/solforge` (plus `--target` variants as needed).
+- Document the build pipeline and configuration flags in README.
+
+## Testing & Validation
+- Unit tests for server proxy functions (if `/api/*` implemented).
+- bun/react tests for Airdrop/Mint form logic and API wrappers (mock RPC responses).
+- Manual pass: start binary, verify RPC on configured port, GUI on configured GUI port (default 42069), confirm initial data loads, perform SOL airdrop and SPL mint, observe Tailwind dark theme.
+
+## Open Questions / Follow-Ups
+- Confirm whether hot reload/dev mode is desired for GUI during development (might require separate Bun serve workflow).
+- Define behaviour of "Add program/token" buttons (link to CLI instructions vs. future modals).
+- Revisit WebSocket streaming for real-time updates once base experience lands.
+
+## Phased Milestones
+- MVP (Foundations)
+  - Binary boots RPC (8899) and GUI (42069).
+  - Static GUI served with Tailwind dark theme.
+  - Airdrop SOL and Mint SPL via JSON-RPC proxy; show signature + status.
+  - Programs and Tokens lists load via RPC calls; manual refresh works.
+  - Config supports `guiPort`; README section for access instructions.
+- Beta (Quality & DX)
+  - Polling hooks with backoff and pause-on-visibility-hidden.
+  - Error toasts, loading states, empty states across sections.
+  - Minimal e2e smoke via `bun:test` + mocked RPC.
+  - Basic stats card auto-refresh; faucet balance warning threshold.
+- v1.0 (Polish & Extensibility)
+  - Persist lightweight UI prefs (e.g., last-selected mint) in `localStorage`.
+  - Optional WS streaming behind flag (no regressions if disabled).
+  - Pluggable card registry for future views (accounts, logs, etc.).
+
+## `/api` Facade Spec
+- POST `/api/jsonrpc`
+  - Body: JSON-RPC 2.0 request object (single), forwarded to local RPC port.
+  - Response: raw JSON-RPC 2.0 response from RPC server.
+  - Rationale: keep browser code small; batching can arrive later.
+- GET `/api/stats`
+  - Aggregates: `getSlot`, `getBlockHeight`, `getLatestBlockhash`, `getTransactionCount` and faucet balance if available.
+  - Response: `{ slot, blockHeight, transactionCount, latestBlockhash, faucetLamports }`.
+  - Implementation: executes a few internal JSON-RPC calls and composes result.
+
+## Frontend Layout (kebab-case)
+```
+src/gui/
+├── index.html                 # Bun HTML import target
+├── public/
+│   └── tailwind.css           # built CSS (minified)
+└── src/
+    ├── index.tsx              # app bootstrap
+    ├── api.ts                 # typed RPC helpers via /api/jsonrpc
+    ├── hooks/
+    │   ├── use-polling.ts     # interval/backoff + visibility handling
+    │   └── use-rpc.ts         # generic JSON-RPC caller
+    ├── components/
+    │   ├── app-shell.tsx
+    │   ├── airdrop-mint-form.tsx
+    │   ├── rpc-stats-card.tsx
+    │   ├── programs-list.tsx
+    │   └── tokens-list.tsx
+    └── types.ts               # minimal UI-facing types (no any)
+```
+
+## Config Additions
+- Extend `sf.config.json` with:
+  - `guiPort: number` (default 42069)
+- Type shape (TS):
+```ts
+export interface SolforgeConfig {
+  rpcPort: number;
+  wsPort?: number;
+  guiPort: number; // new
+  // ...existing fields
+}
+```
+- Setup wizard: prompt for GUI port alongside RPC/WS.
+
+## Server Wiring Sketch (Bun)
+```ts
+// pseudo-code outline
+const gui = Bun.serve({
+  port: config.guiPort ?? 42069,
+  async fetch(req) {
+    const url = new URL(req.url);
+    if (req.method === "POST" && url.pathname === "/api/jsonrpc") {
+      // forward body to local RPC server without network hop
+      const body = await req.text();
+      const resp = await rpcServer.handleJson(body); // call into in-process handler
+      return new Response(resp, { headers: { "content-type": "application/json" } });
+    }
+    if (req.method === "GET" && url.pathname === "/api/stats") {
+      const [slot, blockHeight, txCount, bh, faucet] = await Promise.all([
+        rpc.call("getSlot"),
+        rpc.call("getBlockHeight"),
+        rpc.call("getTransactionCount"),
+        rpc.call("getLatestBlockhash"),
+        rpc.call("getBalance", [faucetPubkey]).catch(() => 0n),
+      ]);
+      return Response.json({ slot, blockHeight, transactionCount: txCount, latestBlockhash: bh.blockhash, faucetLamports: faucet });
+    }
+    // static index + assets
+    if (url.pathname === "/") return new Response(Bun.file("src/gui/index.html"));
+    if (url.pathname === "/tailwind.css") return new Response(Bun.file("src/gui/public/tailwind.css"));
+    return new Response("Not found", { status: 404 });
+  },
+});
+```
+
+## API Helpers (browser)
+- `api.jsonrpc<T>(method: string, params: unknown[]): Promise<T>`
+- `api.getStats(): Promise<{ slot: number; blockHeight: number; transactionCount: number; latestBlockhash: string; faucetLamports: bigint }>`
+- Prefer `bigint` for lamports; stringify via custom JSON replacer only at the display boundary.
+
+## Tailwind Build
+- Build once before compile: `bunx tailwindcss -i src/gui/src/index.css -o src/gui/public/tailwind.css --minify`.
+- Ensure the CSS output path is included in the module graph or accessed via `Bun.file()`.
+
+## Testing Plan (bun:test)
+- API facade
+  - Forwards JSON-RPC body unchanged; returns response as-is.
+  - `/api/stats` composes values and handles RPC failure gracefully.
+- Hooks
+  - `use-polling` respects visibility, clears timers on unmount, backs-off on errors.
+- Components
+  - Airdrop/Mint: disables submit during in-flight; shows signature; polls `getSignatureStatuses` until "confirmed".
+  - Lists: render empty states and error banners.
+
+## Acceptance Criteria (MVP)
+- Binary launches; visiting `http://localhost:42069/` shows GUI without extra build steps.
+- Clicking "Airdrop SOL" on a valid address yields a signature and a confirmed status.
+- Selecting a mint and submitting "Mint Tokens" yields a signature and confirmation.
+- Programs and Tokens sections render data or a clear empty state.
+- Stats card refreshes automatically and never blocks the UI.
+
+## Risks & Constraints
+- Embedding assets: keep the GUI asset set small to avoid bloating the single-file binary.
+- BigInt in JSON: do not leak `bigint` directly through JSON; cast to string only in UI.
+- Cross-origin: prefer same-origin via GUI `/api/*` to avoid CORS complexity.
+
+## Work Checklist
+- [ ] Add `guiPort` to config + setup wizard
+- [ ] Implement GUI `Bun.serve` with `/api/jsonrpc`, `/api/stats`, and static routes
+- [ ] Add Tailwind pipeline and base dark theme
+- [ ] Scaffold frontend layout and components
+- [ ] Implement `api.ts` with JSON-RPC helper
+- [ ] Wire Airdrop/Mint form to RPC
+- [ ] Implement polling hooks and stats card
+- [ ] Write unit tests for facade, hooks, and form logic
+- [ ] Update README with GUI usage and ports

package/drizzle/0000_friendly_millenium_guard.sql

@@ -0,0 +1,53 @@
+CREATE TABLE `accounts` (
+	`address` text PRIMARY KEY NOT NULL,
+	`lamports` integer NOT NULL,
+	`owner_program` text NOT NULL,
+	`executable` integer NOT NULL,
+	`rent_epoch` integer NOT NULL,
+	`data_len` integer NOT NULL,
+	`data_base64` text,
+	`last_slot` integer NOT NULL
+);
+--> statement-breakpoint
+CREATE INDEX `idx_accounts_owner` ON `accounts` (`owner_program`);--> statement-breakpoint
+CREATE INDEX `idx_accounts_last_slot` ON `accounts` (`last_slot`);--> statement-breakpoint
+CREATE TABLE `address_signatures` (
+	`address` text NOT NULL,
+	`signature` text NOT NULL,
+	`slot` integer NOT NULL,
+	`err` integer NOT NULL,
+	`block_time` integer,
+	PRIMARY KEY(`address`, `signature`)
+);
+--> statement-breakpoint
+CREATE INDEX `idx_address_signatures_addr_slot` ON `address_signatures` (`address`,`slot`);--> statement-breakpoint
+CREATE TABLE `transactions` (
+	`signature` text PRIMARY KEY NOT NULL,
+	`slot` integer NOT NULL,
+	`block_time` integer,
+	`version` text NOT NULL,
+	`err_json` text,
+	`fee` integer NOT NULL,
+	`raw_base64` text NOT NULL,
+	`pre_balances_json` text NOT NULL,
+	`post_balances_json` text NOT NULL,
+	`logs_json` text NOT NULL
+);
+--> statement-breakpoint
+CREATE INDEX `idx_transactions_slot` ON `transactions` (`slot`);--> statement-breakpoint
+CREATE TABLE `tx_accounts` (
+	`signature` text NOT NULL,
+	`account_index` integer NOT NULL,
+	`address` text NOT NULL,
+	`signer` integer NOT NULL,
+	`writable` integer NOT NULL,
+	`program_id_index` integer,
+	PRIMARY KEY(`signature`, `account_index`)
+);
+--> statement-breakpoint
+CREATE INDEX `idx_tx_accounts_address` ON `tx_accounts` (`address`);--> statement-breakpoint
+CREATE INDEX `idx_tx_accounts_address_signature` ON `tx_accounts` (`address`,`signature`);--> statement-breakpoint
+CREATE TABLE `meta_kv` (
+	`key` text PRIMARY KEY NOT NULL,
+	`value` text NOT NULL
+);

package/drizzle/0001_stale_sentinels.sql

@@ -0,0 +1,2 @@
+ALTER TABLE `transactions` ADD `pre_token_balances_json` text DEFAULT '[]' NOT NULL;--> statement-breakpoint
+ALTER TABLE `transactions` ADD `post_token_balances_json` text DEFAULT '[]' NOT NULL;