starkfi 0.1.0 → 0.2.0

package/package.json

@@ -1,83 +1,89 @@
 {
-  "name": "starkfi",
-  "version": "0.1.0",
-  "description": "Starknet DeFi CLI + MCP Server — Token swaps, staking, lending, gasless transactions",
-  "type": "module",
-  "bin": {
-    "starkfi": "./dist/index.js"
-  },
-  "main": "./dist/index.js",
-  "exports": {
-    ".": {
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
-    }
-  },
-  "files": [
-    "dist",
-    "README.md",
-    "LICENSE"
-  ],
-  "keywords": [
-    "starknet",
-    "defi",
-    "cli",
-    "mcp",
-    "mcp-server",
-    "starkzap",
-    "swap",
-    "staking",
-    "lending",
-    "vesu",
-    "fibrous",
-    "web3",
-    "l2"
-  ],
-  "author": "ahmetenesdur",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/ahmetenesdur/starkfi.git"
-  },
-  "bugs": {
-    "url": "https://github.com/ahmetenesdur/starkfi/issues"
-  },
-  "homepage": "https://github.com/ahmetenesdur/starkfi#readme",
-  "engines": {
-    "node": ">=18"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.27.1",
-    "chalk": "^5.6.2",
-    "commander": "^14.0.3",
-    "env-paths": "^3.0.0",
-    "inquirer": "^13.3.0",
-    "ora": "^9.3.0",
-    "starknet": "^9.2.1",
-    "starkzap": "^1.0.0",
-    "zod": "^4.3.6"
-  },
-  "devDependencies": {
-    "@eslint/js": "^10.0.1",
-    "@types/node": "^22.19.11",
-    "eslint": "^10.0.2",
-    "eslint-config-prettier": "^10.1.8",
-    "globals": "^17.3.0",
-    "jiti": "^2.6.1",
-    "prettier": "^3.8.1",
-    "tsx": "^4.21.0",
-    "typescript": "^5.9.3",
-    "typescript-eslint": "^8.56.1"
-  },
-  "scripts": {
-    "build": "tsc",
-    "dev": "node --import tsx/esm src/index.ts",
-    "typecheck": "tsc --noEmit",
-    "lint": "eslint src/",
-    "lint:fix": "eslint src/ --fix",
-    "format": "prettier --write src/",
-    "format:check": "prettier --check src/",
-    "start": "node dist/index.js",
-    "mcp-start": "node dist/index.js mcp-start"
-  }
-}
+	"name": "starkfi",
+	"version": "0.2.0",
+	"description": "Starknet DeFi CLI + MCP Server — Swaps, multi-swap, batch (multicall), staking, lending, simulation, portfolio, gasless transactions",
+	"type": "module",
+	"bin": {
+		"starkfi": "./dist/index.js"
+	},
+	"main": "./dist/index.js",
+	"exports": {
+		".": {
+			"import": "./dist/index.js",
+			"types": "./dist/index.d.ts"
+		}
+	},
+	"files": [
+		"dist",
+		"skills",
+		"README.md",
+		"MCP.md",
+		"LICENSE"
+	],
+	"scripts": {
+		"build": "tsc -p tsconfig.build.json",
+		"dev": "node --import tsx/esm src/index.ts",
+		"typecheck": "tsc --noEmit",
+		"lint": "eslint src/",
+		"lint:fix": "eslint src/ --fix",
+		"format": "prettier --write src/",
+		"format:check": "prettier --check src/",
+		"start": "node dist/index.js",
+		"mcp-start": "node dist/index.js mcp-start",
+		"prepublishOnly": "pnpm run build"
+	},
+	"keywords": [
+		"starknet",
+		"defi",
+		"cli",
+		"mcp",
+		"mcp-server",
+		"starkzap",
+		"swap",
+		"multi-swap",
+		"batch",
+		"multicall",
+		"simulation",
+		"portfolio",
+		"staking",
+		"lending",
+		"vesu",
+		"fibrous",
+		"web3",
+		"l2"
+	],
+	"author": "ahmetenesdur",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/ahmetenesdur/starkfi.git"
+	},
+	"bugs": {
+		"url": "https://github.com/ahmetenesdur/starkfi/issues"
+	},
+	"homepage": "https://github.com/ahmetenesdur/starkfi#readme",
+	"engines": {
+		"node": ">=18"
+	},
+	"dependencies": {
+		"@modelcontextprotocol/sdk": "^1.27.1",
+		"chalk": "^5.6.2",
+		"commander": "^14.0.3",
+		"env-paths": "^3.0.0",
+		"ora": "^9.3.0",
+		"starkzap": "^1.0.0",
+		"zod": "^4.3.6"
+	},
+	"devDependencies": {
+		"@eslint/js": "^10.0.1",
+		"@types/node": "^22.19.15",
+		"eslint": "^10.0.3",
+		"eslint-config-prettier": "^10.1.8",
+		"globals": "^17.4.0",
+		"jiti": "^2.6.1",
+		"prettier": "^3.8.1",
+		"tsx": "^4.21.0",
+		"typescript": "^5.9.3",
+		"typescript-eslint": "^8.56.1"
+	}
+}

package/skills/README.md

@@ -0,0 +1,63 @@
+# StarkFi Skills
+
+Agent Skills for the [StarkFi](https://github.com/ahmetenesdur/starkfi) CLI — a Starknet DeFi toolkit.
+
+## Available Skills
+
+| Skill                                                 | Category    | Description                                                       |
+| ----------------------------------------------------- | ----------- | ----------------------------------------------------------------- |
+| [authenticate-wallet](./authenticate-wallet/SKILL.md) | auth        | Email OTP login, session management, wallet deploy                |
+| [balance](./balance/SKILL.md)                         | wallet-data | Check STRK, ETH, and ERC-20 token balances                        |
+| [send](./send/SKILL.md)                               | transaction | Transfer tokens to a Starknet address                             |
+| [trade](./trade/SKILL.md)                             | transaction | Swap tokens via Fibrous aggregation                               |
+| [multi-swap](./multi-swap/SKILL.md)                   | transaction | Multiple swaps in one transaction (up to 3)                       |
+| [batch](./batch/SKILL.md)                             | transaction | Combine swap + stake + supply + send in one multicall             |
+| [staking](./staking/SKILL.md)                         | transaction | Stake, unstake, claim, compound (STRK, WBTC, tBTC, SolvBTC, LBTC) |
+| [lending](./lending/SKILL.md)                         | transaction | Vesu V2 lending: supply, borrow, repay, withdraw, close           |
+| [portfolio](./portfolio/SKILL.md)                     | wallet-data | Aggregated DeFi dashboard with USD valuations                     |
+| [config](./config/SKILL.md)                           | utility     | RPC, network, gas settings, transaction status                    |
+
+## Installation
+
+Install with [Vercel's Skills CLI](https://skills.sh):
+
+```bash
+npx skills add ahmetenesdur/starkfi
+```
+
+Or clone directly:
+
+```bash
+git clone https://github.com/ahmetenesdur/starkfi.git
+```
+
+## Getting Started
+
+1. Install Node.js (v18+) and npm.
+2. No manual installation needed — all skills use `npx starkfi@latest`.
+
+## Typical Workflow
+
+1. **Authenticate** → `authenticate-wallet` (required first)
+2. **Check funds** → `balance` or `portfolio`
+3. **Execute** → `send`, `trade`, `multi-swap`, `batch`, `staking`, or `lending`
+4. **Verify** → `tx-status` (via `config` skill)
+
+## Trigger Examples
+
+| User says...                        | Skill triggered       |
+| ----------------------------------- | --------------------- |
+| "Log me in with my email"           | `authenticate-wallet` |
+| "How much STRK do I have?"          | `balance`             |
+| "Send 10 USDC to 0x04a3..."         | `send`                |
+| "Swap 100 USDC for ETH"             | `trade`               |
+| "Swap USDC to ETH and USDT to STRK" | `multi-swap`          |
+| "Swap ETH and then stake STRK"      | `batch`               |
+| "Stake 1000 STRK with Juno"         | `staking`             |
+| "Supply 500 USDC to Genesis pool"   | `lending`             |
+| "Show me my portfolio"              | `portfolio`           |
+| "I'm getting rate limit errors"     | `config`              |
+
+## License
+
+MIT

package/skills/authenticate-wallet/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: authenticate-wallet
+description: Authenticate, manage sessions, and deploy Starknet wallets with StarkFi. Handles email OTP login (two-step), session checks, address display, account deployment, and logout. Use this skill whenever the user wants to sign in, log in, check their session, see their wallet address, deploy their account, or log out — even if they don't say "authenticate" explicitly.
+license: MIT
+compatibility: Requires Node.js 18+ and npx.
+metadata:
+    version: 0.1.0
+    author: ahmetenesdur
+    category: auth
+allowed-tools:
+    - Bash(npx starkfi@latest auth login *)
+    - Bash(npx starkfi@latest auth verify *)
+    - Bash(npx starkfi@latest auth logout)
+    - Bash(npx starkfi@latest status)
+    - Bash(npx starkfi@latest address)
+    - Bash(npx starkfi@latest deploy)
+---
+
+# Authenticate Wallet
+
+Manage authentication sessions for the StarkFi CLI. StarkFi uses a remote Auth Server with Privy TEE for email-based one-time password (OTP) authentication. A valid session is required before any transactional skill can operate.
+
+## Prerequisites
+
+- The StarkFi Auth Server (`starkfi-server`) must be running and accessible.
+- An email address the user has access to (for receiving OTP codes).
+
+## Authentication Flow
+
+The login process is a **two-step** OTP flow:
+
+1. **Initiate** — `auth login <email>` sends an OTP code to the email.
+2. **Verify** — `auth verify <email> <code>` completes authentication.
+
+The agent CANNOT guess or auto-fill the OTP code — it must wait for the user to provide it after checking their email.
+
+## Rules
+
+1. ALWAYS run `npx starkfi@latest status` first to check if the user already has an active session. If they do, skip the login flow — just inform them.
+2. After `auth login`, you MUST wait for the user to provide their OTP code. Do NOT ask more than once; just say you're waiting.
+3. After `auth verify`, you MUST run `npx starkfi@latest status` to confirm the session is active.
+4. `deploy` is idempotent — it's safe to run multiple times. It deploys the smart account contract on-chain if not already deployed.
+5. If any other skill reports `Not authenticated`, direct the user to this skill.
+
+## Commands
+
+```bash
+# Step 1: Send OTP to email
+npx starkfi@latest auth login <email>
+
+# Step 2: Verify OTP code
+npx starkfi@latest auth verify <email> <code>
+
+# Check session status
+npx starkfi@latest status
+
+# Display wallet address
+npx starkfi@latest address
+
+# Deploy smart account on-chain
+npx starkfi@latest deploy
+
+# End session
+npx starkfi@latest auth logout
+```
+
+## Parameters
+
+| Parameter | Type   | Description                  | Required |
+| --------- | ------ | ---------------------------- | -------- |
+| `email`   | string | User's email address         | Yes      |
+| `code`    | string | One-time password from email | Yes      |
+
+## Examples
+
+**User:** "Log me in with user@example.com"
+
+```bash
+npx starkfi@latest status
+# If not authenticated:
+npx starkfi@latest auth login user@example.com
+# Wait for user to provide OTP code (e.g. "123456")
+npx starkfi@latest auth verify user@example.com 123456
+npx starkfi@latest status
+```
+
+**User:** "What's my wallet address?"
+
+```bash
+npx starkfi@latest address
+```
+
+**User:** "Deploy my account"
+
+```bash
+npx starkfi@latest deploy
+```
+
+**User:** "Log me out"
+
+```bash
+npx starkfi@latest auth logout
+```
+
+## Error Handling
+
+| Error                  | Action                                                                      |
+| ---------------------- | --------------------------------------------------------------------------- |
+| `Invalid OTP code`     | Ask the user to check their email and retry `auth verify`.                  |
+| `Session expired`      | Restart from `auth login`.                                                  |
+| `Server unreachable`   | Ensure `starkfi-server` is running at the configured URL.                   |
+| `Rate limit`           | Wait 60 seconds before retrying.                                            |
+| `Deployment failed`    | Check balance — send ETH/STRK to the address, or enable gasfree mode first. |
+| `Insufficient balance` | For deploy: `npx starkfi@latest config set-gasfree on` to bypass gas costs. |
+
+## Related Skills
+
+- All other skills depend on this skill — if any reports `Not authenticated`, use this.
+- Use `config` to enable gasfree mode if the user can't afford deployment gas.

package/skills/balance/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: balance
+description: Check Starknet wallet token balances — STRK, ETH, and all ERC-20 tokens. Use this skill when the user asks about their balance, holdings, funds, tokens, or wants to know how much of something they have. Also use before any transaction to verify sufficient funds.
+license: MIT
+compatibility: Requires Node.js 18+ and npx.
+metadata:
+    version: 0.1.0
+    author: ahmetenesdur
+    category: wallet-data
+allowed-tools:
+    - Bash(npx starkfi@latest balance)
+    - Bash(npx starkfi@latest balance *)
+    - Bash(npx starkfi@latest status)
+---
+
+# Check Balance
+
+Fetch wallet holdings on Starknet: STRK, ETH, and all ERC-20 tokens with non-zero balances.
+
+## Prerequisites
+
+- Active session required. If not authenticated, run `authenticate-wallet` skill first.
+
+## Rules
+
+1. If the user asks to check a specific token, use `--token <symbol>`.
+2. If no token is specified, run `balance` without flags to show all balances.
+3. Use `--json` when the output will be consumed by another skill or pipeline.
+4. Run this BEFORE `send`, `trade`, `multi-swap`, or any transactional skill to verify sufficient funds.
+
+## Commands
+
+```bash
+# All token balances
+npx starkfi@latest balance [--json]
+
+# Specific token balance
+npx starkfi@latest balance --token <symbol> [--json]
+```
+
+## Parameters
+
+| Parameter | Type   | Description                               | Required |
+| --------- | ------ | ----------------------------------------- | -------- |
+| `--token` | string | Token symbol (e.g. `STRK`, `ETH`, `USDC`) | No       |
+| `--json`  | flag   | Output as JSON                            | No       |
+
+## Examples
+
+**User:** "Check my balance"
+
+```bash
+npx starkfi@latest balance
+```
+
+**User:** "How much STRK do I have?"
+
+```bash
+npx starkfi@latest balance --token STRK
+```
+
+**User:** "Get my balances as JSON"
+
+```bash
+npx starkfi@latest balance --json
+```
+
+## Error Handling
+
+| Error               | Action                                                           |
+| ------------------- | ---------------------------------------------------------------- |
+| `Not authenticated` | Run `authenticate-wallet` skill first.                           |
+| `Network error`     | Retry once. If persistent, use `config` skill to set custom RPC. |
+
+## Related Skills
+
+- Run this BEFORE `send` or `trade` to verify sufficient funds.
+- Run this BEFORE `staking` to confirm available STRK/BTC tokens.
+- Run this BEFORE `lending` supply operations to confirm available assets.
+- Use `portfolio` for a complete view including staking and lending positions with USD values.

package/skills/batch/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: batch
+description: Execute multiple different DeFi operations in a single Starknet transaction — combine swaps, staking, lending supply, and token sends into one multicall. Use this skill when the user wants to batch, combine, or chain multiple diverse operations together, such as "swap ETH and then stake STRK" in one go.
+license: MIT
+compatibility: Requires Node.js 18+ and npx.
+metadata:
+    version: 0.1.0
+    author: ahmetenesdur
+    category: transaction
+allowed-tools:
+    - Bash(npx starkfi@latest batch *)
+    - Bash(npx starkfi@latest status)
+    - Bash(npx starkfi@latest balance)
+    - Bash(npx starkfi@latest balance *)
+    - Bash(npx starkfi@latest tx-status *)
+---
+
+# Batch Execute
+
+Bundle multiple diverse DeFi operations into a single Starknet multicall transaction. Supports combining **swaps**, **staking**, **lending supply**, and **token sends** — all executed atomically in one on-chain call.
+
+## Prerequisites
+
+- Active session required.
+- Sufficient balance for all operations + gas fees.
+- Minimum **2 operations** required per batch.
+
+## Rules
+
+1. BEFORE any batch, you MUST run `npx starkfi@latest status` and `npx starkfi@latest balance` to verify connectivity and funds.
+2. A batch MUST include at least **2 operations**. For single operations, use the dedicated skill (`trade`, `send`, `staking`, or `lending`).
+3. Each `--swap`, `--stake`, `--supply`, and `--send` flag can appear **multiple times** (repeatable).
+4. Suggest using `--simulate` first to verify the entire batch would succeed.
+5. AFTER a successful batch, verify with `npx starkfi@latest tx-status <hash>`.
+6. All operations in a batch are **atomic** — if any one fails, the entire transaction reverts.
+
+## Commands
+
+```bash
+npx starkfi@latest batch [--simulate] [--json] \
+  --swap "<amount> <from> <to>" \
+  --stake "<amount> <token> <validator_or_pool>" \
+  --supply "<amount> <token> <pool_address>" \
+  --send "<amount> <token> <recipient>"
+```
+
+## Operation Formats
+
+| Flag       | Format                                     | Example                         |
+| ---------- | ------------------------------------------ | ------------------------------- |
+| `--swap`   | `"<amount> <from> <to>"`                   | `--swap "100 USDC ETH"`         |
+| `--stake`  | `"<amount> <token> <validator_or_0xPool>"` | `--stake "500 STRK Juno"`       |
+| `--supply` | `"<amount> <token> <0xPool>"`              | `--supply "100 USDC 0x04a3..."` |
+| `--send`   | `"<amount> <token> <0xRecipient>"`         | `--send "10 STRK 0x07b2..."`    |
+
+> **Note:** `--stake` accepts either a validator name (e.g. `Juno`) or a pool contract address (starting with `0x`). The CLI auto-detects the format.
+
+## Parameters
+
+| Parameter    | Type   | Description                           | Required |
+| ------------ | ------ | ------------------------------------- | -------- |
+| `--swap`     | string | Swap operation (repeatable)           | No\*     |
+| `--stake`    | string | Stake operation (repeatable)          | No\*     |
+| `--supply`   | string | Lending supply operation (repeatable) | No\*     |
+| `--send`     | string | Token transfer operation (repeatable) | No\*     |
+| `--simulate` | flag   | Estimate fees without broadcasting    | No       |
+| `--json`     | flag   | Output as JSON                        | No       |
+
+\*At least 2 operations (of any type) are required.
+
+## Examples
+
+**User:** "Swap 100 USDC to ETH and stake 500 STRK with Juno in one transaction"
+
+```bash
+npx starkfi@latest status
+npx starkfi@latest balance
+npx starkfi@latest batch --swap "100 USDC ETH" --stake "500 STRK Juno"
+npx starkfi@latest tx-status <hash>
+```
+
+**User:** "Batch: swap 50 USDT to STRK, supply 100 USDC and send 10 STRK"
+
+```bash
+npx starkfi@latest status
+npx starkfi@latest balance
+npx starkfi@latest batch \
+  --swap "50 USDT STRK" \
+  --supply "100 USDC 0x04a3..." \
+  --send "10 STRK 0x07b2..."
+npx starkfi@latest tx-status <hash>
+```
+
+**User:** "Simulate a batch of two swaps and a stake"
+
+```bash
+npx starkfi@latest batch --simulate \
+  --swap "100 USDC ETH" \
+  --swap "200 USDT STRK" \
+  --stake "500 STRK Juno"
+```
+
+## Error Handling
+
+| Error                    | Action                                                        |
+| ------------------------ | ------------------------------------------------------------- |
+| `Too few operations`     | At least 2 operations required. Use dedicated skills instead. |
+| `Insufficient balance`   | Check `balance` for all required tokens.                      |
+| `Invalid validator/pool` | Run `validators`/`pools` to find valid names/addresses.       |
+| `Simulation failed`      | One of the operations would revert. Check each individually.  |
+| `Not authenticated`      | Run `authenticate-wallet` skill first.                        |
+
+## Related Skills
+
+- Use `trade` for a single swap.
+- Use `staking` for standalone staking operations.
+- Use `lending` for standalone lending operations.
+- Use `send` for standalone token transfers.