Development & Contributing

Prerequisites

• Node.js v18 or later
• pnpm (recommended) — install via npm install -g pnpm
• Git

Local Setup

# Clone the repository
git clone https://github.com/ahmetenesdur/starkfi.git
cd starkfi

# Install dependencies
pnpm install

Build

Compile TypeScript to the dist/ directory:

pnpm build

This produces production-ready JavaScript in dist/. The prepublishOnly script runs pnpm build automatically before npm publish.

Dev Mode

Run the CLI directly from TypeScript source via tsx:

pnpm dev balance
pnpm dev trade 100 USDC ETH --simulate
pnpm dev config list

Lint & Format

StarkFi uses ESLint for linting and Prettier for code formatting, both configured for TypeScript strict mode:

pnpm lint          # Check for lint issues
pnpm lint:fix      # Auto-fix lint issues
pnpm format        # Format all source files
pnpm format:check  # Check formatting without writing
pnpm typecheck     # TypeScript type checking (no emit)

Auth Server

The auth server (server/) must be running for authentication, signing, and gas abstraction. See the Auth Server page for full setup instructions.

Quick start:

cd server
pnpm install
cp .env.example .env   # Add your Privy credentials
pnpm dev

Project Scripts

Contributing

Contributions are welcome! Here's how to get started:

1. Fork the repository and create a feature branch
2. Install dependencies: pnpm install
3. Make your changes following the existing code style:
   • TypeScript strict mode
   • ESLint + Prettier formatting
   • Service layer isolation (see Architecture)
4. Build and verify:

   pnpm build && pnpm lint

5. Submit a pull request with a clear description of your changes

Code Style Guidelines

• Use the existing patterns — service layer isolation, Zod schemas, error handling via StarkfiError
• All network operations should use withRetry() for automatic retry
• New CLI commands go in src/commands/<group>/
• New MCP tools need a registration file in src/mcp/tools/ and a handler in src/mcp/handlers/
• New services go in src/services/<name>/

Bug Reports & Feature Requests

For bugs and feature requests, please open an issue with:

• A clear description of the problem or feature
• Steps to reproduce (for bugs)
• Expected vs actual behavior