solforge 0.1.6 → 0.2.0

package/.claude/settings.local.json

@@ -0,0 +1,9 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(bun run:*)"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}

package/.github/workflows/release-binaries.yml

@@ -0,0 +1,133 @@
+name: Build and Release Binaries
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  actions: read
+
+jobs:
+  check-version:
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.get_version.outputs.version }}
+      tag_exists: ${{ steps.check_tag.outputs.exists }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Get version from package.json
+        id: get_version
+        run: echo "version=$(node -p \"require('./package.json').version\")" >> $GITHUB_OUTPUT
+
+      - name: Check if version tag exists
+        id: check_tag
+        run: |
+          if git rev-parse "v${{ steps.get_version.outputs.version }}" >/dev/null 2>&1; then
+            echo "exists=true" >> $GITHUB_OUTPUT
+            echo "Tag v${{ steps.get_version.outputs.version }} already exists, skipping"
+          else
+            echo "exists=false" >> $GITHUB_OUTPUT
+            echo "Tag v${{ steps.get_version.outputs.version }} does not exist, proceeding"
+          fi
+
+  build-binaries:
+    needs: check-version
+    if: needs.check-version.outputs.tag_exists == 'false'
+    runs-on: ${{ matrix.runner }}
+    strategy:
+      matrix:
+        include:
+          - os: darwin
+            arch: x64
+            runner: macos-latest
+          - os: darwin
+            arch: arm64
+            runner: macos-latest
+          - os: linux
+            arch: x64
+            runner: ubuntu-latest
+          - os: linux
+            arch: arm64
+            runner: ubuntu-latest
+          - os: windows
+            arch: x64
+            runner: windows-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: oven-sh/setup-bun@v1
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install
+
+      - name: Build binary
+        shell: bash
+        run: |
+          mkdir -p dist
+          TARGET="bun-${{ matrix.os }}-${{ matrix.arch }}"
+          OUTFILE="dist/solforge-${{ matrix.os }}-${{ matrix.arch }}${{ matrix.os == 'windows' && '.exe' || '' }}"
+          bun build --compile --target="$TARGET" src/cli/main.ts --outfile "$OUTFILE"
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: solforge-${{ matrix.os }}-${{ matrix.arch }}
+          path: dist/solforge-${{ matrix.os }}-${{ matrix.arch }}${{ matrix.os == 'windows' && '.exe' || '' }}
+
+  publish:
+    needs: [check-version, build-binaries]
+    if: needs.check-version.outputs.tag_exists == 'false'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Download all artifacts
+        uses: actions/download-artifact@v4
+        with:
+          path: ./artifacts
+
+      - name: Flatten artifacts
+        run: |
+          mkdir -p ./release
+          find ./artifacts -type f -exec cp {} ./release/ \;
+          ls -la ./release/
+
+      - name: Create and push git tag
+        run: |
+          VERSION=$(node -p "require('./package.json').version")
+          git config --local user.email "action@github.com"
+          git config --local user.name "GitHub Action"
+          git tag "v${VERSION}"
+          git push origin "v${VERSION}"
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: v${{ needs.check-version.outputs.version }}
+          name: "SolForge v${{ needs.check-version.outputs.version }}"
+          body: |
+            ## SolForge v${{ needs.check-version.outputs.version }}
+
+            Platform binaries are attached below.
+
+            - macOS (Intel): solforge-darwin-x64
+            - macOS (Apple Silicon): solforge-darwin-arm64
+            - Linux (x64): solforge-linux-x64
+            - Linux (ARM64): solforge-linux-arm64
+            - Windows (x64): solforge-windows-x64.exe
+          files: ./release/*
+          draft: false
+          prerelease: false
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+

package/AGENTS.md

@@ -0,0 +1,271 @@
+# Development Guidelines for SolForge
+
+## Core Principles
+
+### 1. Keep It Modular
+- **No huge files**: If a file exceeds 200 lines, consider splitting it
+- **Single responsibility**: Each module should do one thing well
+- **Clear boundaries**: Well-defined interfaces between modules
+
+### 2. Keep It Simple
+- **Straightforward code**: Prefer clarity over cleverness
+- **Minimal abstractions**: Only abstract when there's clear benefit
+- **Explicit over implicit**: Make intentions clear in code
+
+### 3. Keep It Fast
+- **Performance matters**: This is a performance-critical tool
+- **Measure first**: Profile before optimizing
+- **Memory conscious**: Avoid unnecessary allocations
+
+## Technology Rules
+
+### Package Manager
+- **ALWAYS use Bun**: No npm, yarn, pnpm, or anything else
+- Commands:
+  - `bun install` (not npm install)
+  - `bun run` (not npm run)
+  - `bun test` (not jest/vitest)
+  - `bun build` (not webpack/esbuild)
+
+### Runtime
+- **Bun exclusively**: Use Bun-native APIs when available
+- Prefer `Bun.serve()` over Express
+- Use `Bun.file()` over `fs.readFile()`
+- Use `bun:test` for testing
+
+## Code Style
+
+### File Naming
+- **kebab-case**: All files use kebab-case
+  - ✅ `rpc-server.ts`
+  - ✅ `get-account-info.ts`
+  - ❌ `rpcServer.ts`
+  - ❌ `GetAccountInfo.ts`
+
+### Directory Structure
+```
+server/
+├── methods/
+│   ├── account/           # When account.ts gets too big
+│   │   ├── get-account-info.ts
+│   │   ├── get-balance.ts
+│   │   ├── get-multiple-accounts.ts
+│   │   └── index.ts
+│   ├── transaction/       # When transaction.ts gets too big
+│   │   ├── send-transaction.ts
+│   │   ├── simulate-transaction.ts
+│   │   └── index.ts
+│   └── index.ts
+```
+
+### File Size Guidelines
+- **< 100 lines**: Ideal file size
+- **100-200 lines**: Acceptable
+- **> 200 lines**: Consider splitting
+- **> 300 lines**: Must split
+
+### When to Split Files
+If `account.ts` or `transaction.ts` grows large:
+1. Create a directory with the same name
+2. Split into individual method files
+3. Create an index.ts that exports everything
+4. Update imports to maintain compatibility
+
+Example migration:
+```typescript
+// Before: server/methods/account.ts (300+ lines)
+export const getAccountInfo = ...
+export const getBalance = ...
+export const requestAirdrop = ...
+
+// After: server/methods/account/index.ts
+export { getAccountInfo } from './get-account-info';
+export { getBalance } from './get-balance';
+export { requestAirdrop } from './request-airdrop';
+```
+
+## TypeScript Guidelines
+
+### Types
+- **Define interfaces**: Use interfaces for object shapes
+- **Avoid `any`**: Use `unknown` if type is truly unknown
+- **Export types**: Keep types in separate files when shared
+
+### Imports
+- **Explicit imports**: Import only what you need
+- **Type imports**: Use `import type` when importing only types
+- **Organized imports**: Group by external, internal, types
+
+```typescript
+// External
+import { PublicKey } from "@solana/web3.js";
+
+// Internal
+import { someHelper } from "../helpers";
+
+// Types
+import type { RpcMethodHandler } from "../types";
+```
+
+## Method Implementation
+
+### Structure
+Each RPC method should follow this pattern:
+
+```typescript
+import type { RpcMethodHandler } from "../types";
+
+export const methodName: RpcMethodHandler = (id, params, context) => {
+  // 1. Parse and validate params
+  const [param1, param2] = params;
+  
+  // 2. Execute logic
+  try {
+    const result = context.svm.someOperation();
+    
+    // 3. Return formatted response
+    return context.createSuccessResponse(id, result);
+  } catch (error: any) {
+    // 4. Handle errors appropriately
+    return context.createErrorResponse(id, -32602, "Error message", error.message);
+  }
+};
+```
+
+### Error Codes
+Use standard JSON-RPC error codes:
+- `-32700`: Parse error
+- `-32600`: Invalid request
+- `-32601`: Method not found
+- `-32602`: Invalid params
+- `-32603`: Internal error
+- `-32000` to `-32099`: Server errors
+
+## Testing
+
+### Test Organization
+- Test files next to source: `method-name.test.ts`
+- Use descriptive test names
+- Test both success and error cases
+
+### Test Structure
+```typescript
+import { test, expect } from "bun:test";
+
+test("getAccountInfo returns account data", async () => {
+  // Arrange
+  const server = createTestServer();
+  
+  // Act
+  const result = await server.handleRequest({...});
+  
+  // Assert
+  expect(result.result).toBeDefined();
+});
+```
+
+## Documentation
+
+### Code Comments
+- **Minimal comments**: Code should be self-documenting
+- **Why, not what**: Explain complex logic, not obvious code
+- **TODO format**: `// TODO: [description]`
+
+### Method Documentation
+Each new RPC method needs:
+1. Entry in README.md
+2. TypeScript types defined
+3. Test coverage
+4. Error cases documented
+
+## Git Workflow
+
+### Commit Messages
+- **Conventional commits**: `type: description`
+- Types: `feat`, `fix`, `docs`, `refactor`, `test`, `chore`
+- Examples:
+  - `feat: add getTokenAccounts RPC method`
+  - `fix: handle empty transaction array`
+  - `refactor: split account methods into separate files`
+
+### Branch Naming
+- `feature/method-name` for new methods
+- `fix/issue-description` for bug fixes
+- `refactor/module-name` for refactoring
+
+## Performance Considerations
+
+### Do's
+- ✅ Use `BigInt` for lamports
+- ✅ Cache frequently accessed data
+- ✅ Use batch operations when possible
+- ✅ Profile before optimizing
+
+### Don'ts
+- ❌ Premature optimization
+- ❌ Synchronous file I/O
+- ❌ Unnecessary object cloning
+- ❌ Large in-memory buffers
+
+## Adding New RPC Methods
+
+### Checklist
+- [ ] Create method file in appropriate directory
+- [ ] Implement method following standard pattern
+- [ ] Add to method exports in index.ts
+- [ ] Register in rpcMethods object
+- [ ] Add tests
+- [ ] Update README.md
+- [ ] Test with real client
+
+### Template
+```typescript
+// server/methods/category/method-name.ts
+import type { RpcMethodHandler } from "../../types";
+
+/**
+ * Implements the getMethodName RPC method
+ * @see https://docs.solana.com/api/http#getmethodname
+ */
+export const getMethodName: RpcMethodHandler = (id, params, context) => {
+  const [param1, config] = params;
+  
+  try {
+    // Implementation
+    const result = {};
+    
+    return context.createSuccessResponse(id, {
+      context: { slot: Number(context.slot) },
+      value: result
+    });
+  } catch (error: any) {
+    return context.createErrorResponse(
+      id, 
+      -32602, 
+      "Invalid params", 
+      error.message
+    );
+  }
+};
+```
+
+## Review Checklist
+
+Before submitting code:
+- [ ] Files under 200 lines
+- [ ] Using kebab-case filenames
+- [ ] No npm/yarn commands
+- [ ] Types properly defined
+- [ ] Errors handled appropriately
+- [ ] Tests written
+- [ ] Documentation updated
+
+## Questions?
+
+When in doubt:
+1. Keep it simple
+2. Keep it modular
+3. Keep it fast
+4. Use Bun
+
+Remember: We're building a tool that developers will use hundreds of times per day. Every millisecond counts, and every good developer experience decision matters.

package/CLAUDE.md

@@ -0,0 +1,106 @@
+
+Default to using Bun instead of Node.js.
+
+- Use `bun <file>` instead of `node <file>` or `ts-node <file>`
+- Use `bun test` instead of `jest` or `vitest`
+- Use `bun build <file.html|file.ts|file.css>` instead of `webpack` or `esbuild`
+- Use `bun install` instead of `npm install` or `yarn install` or `pnpm install`
+- Use `bun run <script>` instead of `npm run <script>` or `yarn run <script>` or `pnpm run <script>`
+- Bun automatically loads .env, so don't use dotenv.
+
+## APIs
+
+- `Bun.serve()` supports WebSockets, HTTPS, and routes. Don't use `express`.
+- `bun:sqlite` for SQLite. Don't use `better-sqlite3`.
+- `Bun.redis` for Redis. Don't use `ioredis`.
+- `Bun.sql` for Postgres. Don't use `pg` or `postgres.js`.
+- `WebSocket` is built-in. Don't use `ws`.
+- Prefer `Bun.file` over `node:fs`'s readFile/writeFile
+- Bun.$`ls` instead of execa.
+
+## Testing
+
+Use `bun test` to run tests.
+
+```ts#index.test.ts
+import { test, expect } from "bun:test";
+
+test("hello world", () => {
+  expect(1).toBe(1);
+});
+```
+
+## Frontend
+
+Use HTML imports with `Bun.serve()`. Don't use `vite`. HTML imports fully support React, CSS, Tailwind.
+
+Server:
+
+```ts#index.ts
+import index from "./index.html"
+
+Bun.serve({
+  routes: {
+    "/": index,
+    "/api/users/:id": {
+      GET: (req) => {
+        return new Response(JSON.stringify({ id: req.params.id }));
+      },
+    },
+  },
+  // optional websocket support
+  websocket: {
+    open: (ws) => {
+      ws.send("Hello, world!");
+    },
+    message: (ws, message) => {
+      ws.send(message);
+    },
+    close: (ws) => {
+      // handle close
+    }
+  },
+  development: {
+    hmr: true,
+    console: true,
+  }
+})
+```
+
+HTML files can import .tsx, .jsx or .js files directly and Bun's bundler will transpile & bundle automatically. `<link>` tags can point to stylesheets and Bun's CSS bundler will bundle.
+
+```html#index.html
+<html>
+  <body>
+    <h1>Hello, world!</h1>
+    <script type="module" src="./frontend.tsx"></script>
+  </body>
+</html>
+```
+
+With the following `frontend.tsx`:
+
+```tsx#frontend.tsx
+import React from "react";
+
+// import .css files directly and it works
+import './index.css';
+
+import { createRoot } from "react-dom/client";
+
+const root = createRoot(document.body);
+
+export default function Frontend() {
+  return <h1>Hello, world!</h1>;
+}
+
+root.render(<Frontend />);
+```
+
+Then, run index.ts
+
+```sh
+bun --hot ./index.ts
+```
+
+For more information, read the Bun API docs in `node_modules/bun-types/docs/**.md`.

package/PROJECT_STRUCTURE.md

@@ -0,0 +1,124 @@
+# SolForge Project Structure
+
+## Current Architecture
+
+```
+solforge/
+├── index.ts                    # Main entry point
+├── server/                     # Core server module
+│   ├── index.ts               # Module exports
+│   ├── rpc-server.ts          # Main RPC server class
+│   ├── types.ts               # Shared TypeScript types
+│   └── methods/               # RPC method implementations
+│       ├── index.ts           # Method registry
+│       ├── account/           # Account methods (modular)
+│       │   ├── index.ts      
+│       │   ├── get-account-info.ts
+│       │   ├── get-balance.ts
+│       │   ├── get-multiple-accounts.ts
+│       │   └── request-airdrop.ts
+│       ├── transaction.ts     # Transaction methods (monolithic for now)
+│       ├── block.ts           # Block/slot methods
+│       ├── system.ts          # System methods
+│       └── TEMPLATE.md        # Template for new methods
+├── test-client.ts             # Test client implementation
+├── package.json               # Dependencies (Bun-based)
+├── tsconfig.json              # TypeScript configuration
+├── SOLFORGE.md                # Project vision and roadmap
+├── AGENTS.md                  # Development guidelines
+├── README.md                  # User documentation
+└── SOLANA_KIT_GUIDE.md        # Solana Kit usage guide
+```
+
+## Module Organization
+
+### When to Split Files
+
+Files start as single modules and split when they exceed 200 lines:
+
+```
+Initial: methods/category.ts (< 200 lines)
+    ↓
+Growth: methods/category.ts (> 200 lines)
+    ↓
+Split: methods/category/
+       ├── index.ts
+       ├── method-one.ts
+       ├── method-two.ts
+       └── method-three.ts
+```
+
+### Current Status
+
+- ✅ **Account methods**: Already modularized (4 methods)
+- 📦 **Transaction methods**: Single file (4 methods, ~145 lines)
+- 📦 **Block methods**: Single file (3 methods, ~20 lines)
+- 📦 **System methods**: Single file (3 methods, ~27 lines)
+
+### Adding New Methods
+
+1. **Determine category** (account/transaction/block/system/custom)
+2. **Check file size** of target category
+3. **If < 200 lines**: Add to existing file
+4. **If > 200 lines**: Create subdirectory structure
+5. **Follow template** in `methods/TEMPLATE.md`
+6. **Register method** in `methods/index.ts`
+7. **Update documentation**
+
+## Key Files
+
+### Core Components
+
+- `server/rpc-server.ts`: Main server class, handles routing
+- `server/types.ts`: TypeScript interfaces for RPC
+- `server/methods/index.ts`: Method registry and exports
+
+### Configuration
+
+- `package.json`: Dependencies (minimal, Bun-focused)
+- `tsconfig.json`: TypeScript settings
+
+### Documentation
+
+- `SOLFORGE.md`: What we're building and why
+- `AGENTS.md`: How to develop for SolForge
+- `README.md`: User-facing documentation
+- `PROJECT_STRUCTURE.md`: This file
+
+## Naming Conventions
+
+- **Files**: `kebab-case.ts`
+- **Directories**: `kebab-case/`
+- **Exports**: `camelCase`
+- **Types/Interfaces**: `PascalCase`
+
+## Import Hierarchy
+
+```typescript
+// 1. External packages
+import { PublicKey } from "@solana/web3.js";
+
+// 2. Internal modules
+import { helper } from "../utils";
+
+// 3. Types
+import type { RpcMethodHandler } from "../types";
+```
+
+## Future Growth
+
+As we add more RPC methods, the structure will evolve:
+
+```
+methods/
+├── account/          # 10+ methods
+├── transaction/      # 8+ methods  
+├── block/           # 5+ methods
+├── system/          # 6+ methods
+├── token/           # Future: SPL token methods
+├── stake/           # Future: Staking methods
+├── vote/            # Future: Vote methods
+└── deprecated/      # Future: Legacy compatibility
+```
+
+Each category becomes modular when it reaches complexity threshold.