starkfi 0.1.0 → 0.2.0

package/skills/config/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: config
+description: View and modify StarkFi CLI configuration — set custom RPC URLs, switch networks, manage gas settings, and check transaction status. Use this skill when the user mentions RPC, rate limits, network settings, gas mode, gas token, configuration, or wants to check a transaction hash.
+license: MIT
+compatibility: Requires Node.js 18+ and npx.
+metadata:
+    version: 0.1.0
+    author: ahmetenesdur
+    category: utility
+allowed-tools:
+    - Bash(npx starkfi@latest config *)
+    - Bash(npx starkfi@latest tx-status *)
+---
+
+# Configuration & Utilities
+
+Manage local configuration for the StarkFi CLI and check transaction status on-chain. Configuration includes RPC endpoints, network selection, and gas payment settings.
+
+## Prerequisites
+
+- None for configuration commands (`config list`, `config set-*`, `config get-rpc`).
+- Active session required for `tx-status` (it reads the network from the session).
+
+## Configuration Commands
+
+```bash
+# List all current settings
+npx starkfi@latest config list
+
+# Set custom RPC URL
+npx starkfi@latest config set-rpc <url>
+
+# Get current RPC URL
+npx starkfi@latest config get-rpc
+
+# Switch network
+npx starkfi@latest config set-network <network>
+
+# Toggle developer-sponsored gas (Gasfree mode)
+npx starkfi@latest config set-gasfree <on|off>
+
+# Set gas payment token (for Gasless mode)
+npx starkfi@latest config set-gas-token <token>
+```
+
+## Transaction Status
+
+```bash
+npx starkfi@latest tx-status <hash>
+```
+
+## Gas Modes
+
+StarkFi supports two gas abstraction modes:
+
+| Mode        | Who Pays      | Command                     | Description                                      |
+| ----------- | ------------- | --------------------------- | ------------------------------------------------ |
+| **Gasfree** | Developer     | `config set-gasfree on`     | Gas fees sponsored by StarkFi via AVNU Paymaster |
+| **Gasless** | User (ERC-20) | `config set-gas-token STRK` | User pays gas in an ERC-20 token (default mode)  |
+
+Supported gas tokens: **ETH**, **STRK**, **USDC**, **USDT**, **DAI**
+
+Gasfree and Gasless are mutually exclusive — enabling one disables the other.
+
+> **Default:** Gasless mode with STRK as gas token. Gas is paid through the AVNU Paymaster, so the user does not need native ETH for gas — any supported ERC-20 works.
+
+## Parameters
+
+| Parameter | Type   | Description                                   | Required |
+| --------- | ------ | --------------------------------------------- | -------- |
+| `url`     | string | Full HTTP(S) RPC endpoint URL                 | Yes      |
+| `network` | string | `mainnet` or `sepolia`                        | Yes      |
+| `on/off`  | string | Enable or disable Gasfree mode                | Yes      |
+| `token`   | string | Gas token symbol or `reset` (reverts to STRK) | Yes      |
+| `hash`    | string | Transaction hash (`0x...`)                    | Yes      |
+
+## Rules
+
+1. **Rate Limits**: If any skill fails with "rate limit" or "429" errors, use `config set-rpc` to set a custom RPC endpoint.
+2. **Persistence**: Settings are stored locally and persist across sessions.
+3. Use `tx-status` AFTER every `send`, `trade`, `multi-swap`, `batch`, and staking/lending transaction to verify success.
+4. Use `config get-rpc` to check the current RPC URL before changing it.
+
+## Examples
+
+**User:** "I'm getting rate limit errors"
+
+```bash
+npx starkfi@latest config get-rpc
+npx starkfi@latest config set-rpc https://starknet-mainnet.g.alchemy.com/v2/<key>
+```
+
+**User:** "Show my current configuration"
+
+```bash
+npx starkfi@latest config list
+```
+
+**User:** "Switch to testnet"
+
+```bash
+npx starkfi@latest config set-network sepolia
+```
+
+**User:** "Enable free gas mode"
+
+```bash
+npx starkfi@latest config set-gasfree on
+```
+
+**User:** "I want to pay gas in USDC"
+
+```bash
+npx starkfi@latest config set-gasfree off
+npx starkfi@latest config set-gas-token USDC
+```
+
+**User:** "Reset gas token to default"
+
+```bash
+npx starkfi@latest config set-gas-token reset
+```
+
+**User:** "Did my transaction go through? Hash is 0xabc..."
+
+```bash
+npx starkfi@latest tx-status 0xabc...
+```
+
+## Error Handling
+
+| Error                   | Action                                              |
+| ----------------------- | --------------------------------------------------- |
+| `Invalid RPC URL`       | Ensure URL starts with `http://` or `https://`.     |
+| `Invalid network`       | Use `mainnet` or `sepolia`.                         |
+| `Unsupported gas token` | Must be one of: ETH, STRK, USDC, USDT, DAI.         |
+| `Transaction not found` | Verify the hash is correct and the network matches. |
+| `Pending`               | Transaction is still in mempool — wait and retry.   |
+
+## Related Skills
+
+- This skill is referenced by all other skills for rate limit recovery.
+- Use `config set-gasfree on` for developer-sponsored gas.
+- Use `tx-status` to verify transactions from any transactional skill.

package/skills/lending/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: lending
+description: Manage Vesu V2 lending positions on Starknet — supply assets, borrow against collateral, repay debt, withdraw, and close positions. Use this skill when the user mentions lending, borrowing, supplying collateral, Vesu, interest, health factor, liquidation, or DeFi yield from lending protocols.
+license: MIT
+compatibility: Requires Node.js 18+ and npx.
+metadata:
+    version: 0.1.0
+    author: ahmetenesdur
+    category: transaction
+allowed-tools:
+    - Bash(npx starkfi@latest lend-pools)
+    - Bash(npx starkfi@latest lend-pools *)
+    - Bash(npx starkfi@latest lend-status *)
+    - Bash(npx starkfi@latest lend-supply *)
+    - Bash(npx starkfi@latest lend-withdraw *)
+    - Bash(npx starkfi@latest lend-borrow *)
+    - Bash(npx starkfi@latest lend-repay *)
+    - Bash(npx starkfi@latest lend-close *)
+    - Bash(npx starkfi@latest status)
+    - Bash(npx starkfi@latest balance)
+    - Bash(npx starkfi@latest balance *)
+    - Bash(npx starkfi@latest tx-status *)
+---
+
+# Lending (Vesu V2)
+
+Manage lending and borrowing positions on Vesu V2 protocol on Starknet. Supply assets to earn yield, borrow against collateral, repay debt, and close positions.
+
+## Prerequisites
+
+- Active session required.
+- Sufficient token balance for supply/repay operations + gas fees.
+
+## Rules
+
+1. BEFORE any lending action, run `npx starkfi@latest lend-pools` to discover available pools and tokens. Use `lend-pools <name>` for detailed pool info including APY rates.
+2. Pool can be specified by **name** (e.g. `Prime`, `Genesis`) or by **contract address** (`0x...`).
+3. BEFORE borrowing, run `npx starkfi@latest lend-status` to check Health Factor:
+    - Health Factor **> 2.0** → Safe to borrow.
+    - Health Factor **1.5 – 2.0** → WARN the user about increasing risk.
+    - Health Factor **< 1.5** → STRONGLY advise against borrowing. Suggest repaying instead.
+    - Health Factor **< 1.1** → DO NOT proceed without explicit double-confirmation from the user.
+4. AFTER any transactional operation, verify with `tx-status`.
+5. When using `--use-supplied`, the borrow is backed by the user's existing vTokens (supplied positions) rather than transferring from wallet.
+
+## Commands
+
+### Discovery
+
+```bash
+# List all pools (overview table)
+npx starkfi@latest lend-pools [--json]
+
+# Detailed pool info with APY rates
+npx starkfi@latest lend-pools <name> [--json]
+
+# View position status
+npx starkfi@latest lend-status --pool <name|address> --collateral-token <symbol> [--borrow-token <symbol>]
+```
+
+### Supply & Withdraw
+
+```bash
+# Supply (deposit assets to earn yield)
+npx starkfi@latest lend-supply <amount> --pool <name|address> --token <symbol>
+
+# Withdraw (remove supplied assets)
+npx starkfi@latest lend-withdraw <amount> --pool <name|address> --token <symbol>
+```
+
+### Borrow & Repay
+
+```bash
+# Borrow (provide collateral and take loan)
+npx starkfi@latest lend-borrow \
+  --pool <name|address> \
+  --collateral-amount <n> --collateral-token <symbol> \
+  --borrow-amount <n> --borrow-token <symbol> \
+  [--use-supplied]
+
+# Repay (pay back borrowed amount)
+npx starkfi@latest lend-repay <amount> --pool <name|address> --token <symbol> --collateral-token <symbol>
+```
+
+### Close Position
+
+```bash
+# Atomically repay all debt and withdraw all collateral
+npx starkfi@latest lend-close --pool <name|address> --collateral-token <symbol> --borrow-token <symbol>
+```
+
+## Parameters
+
+### lend-supply / lend-withdraw
+
+| Parameter | Type   | Description                                | Required |
+| --------- | ------ | ------------------------------------------ | -------- |
+| `amount`  | number | Amount (positional)                        | Yes      |
+| `--pool`  | string | Pool name or address                       | Yes      |
+| `--token` | string | Token symbol (`USDC`, `ETH`, `STRK`, etc.) | Yes      |
+
+### lend-borrow
+
+| Parameter             | Type   | Description                           | Required |
+| --------------------- | ------ | ------------------------------------- | -------- |
+| `--pool`              | string | Pool name or address                  | Yes      |
+| `--collateral-amount` | number | Collateral amount to supply           | Yes      |
+| `--collateral-token`  | string | Collateral token (e.g. `ETH`, `STRK`) | Yes      |
+| `--borrow-amount`     | number | Amount to borrow                      | Yes      |
+| `--borrow-token`      | string | Token to borrow (e.g. `USDC`, `USDT`) | Yes      |
+| `--use-supplied`      | flag   | Use existing vTokens as collateral    | No       |
+
+### lend-repay
+
+| Parameter            | Type   | Description                      | Required |
+| -------------------- | ------ | -------------------------------- | -------- |
+| `amount`             | number | Amount to repay (positional)     | Yes      |
+| `--pool`             | string | Pool name or address             | Yes      |
+| `--token`            | string | Token to repay (e.g. `USDC`)     | Yes      |
+| `--collateral-token` | string | Collateral token of the position | Yes      |
+
+### lend-close
+
+| Parameter            | Type   | Description             | Required |
+| -------------------- | ------ | ----------------------- | -------- |
+| `--pool`             | string | Pool name or address    | Yes      |
+| `--collateral-token` | string | Collateral token symbol | Yes      |
+| `--borrow-token`     | string | Borrow token symbol     | Yes      |
+
+### lend-status
+
+| Parameter            | Type   | Description                            | Required |
+| -------------------- | ------ | -------------------------------------- | -------- |
+| `--pool`             | string | Pool name or address                   | Yes      |
+| `--collateral-token` | string | Token supplied/used as collateral      | Yes      |
+| `--borrow-token`     | string | Borrow token (needed to see debt + HF) | No       |
+
+## Examples
+
+**User:** "What lending pools are available?"
+
+```bash
+npx starkfi@latest lend-pools
+```
+
+**User:** "Show me details for the Prime pool"
+
+```bash
+npx starkfi@latest lend-pools Prime
+```
+
+**User:** "Supply 500 USDC to Prime"
+
+```bash
+npx starkfi@latest status
+npx starkfi@latest balance --token USDC
+npx starkfi@latest lend-supply 500 --pool Prime --token USDC
+npx starkfi@latest tx-status <hash>
+```
+
+**User:** "Borrow 100 USDC with ETH collateral from Prime"
+
+```bash
+npx starkfi@latest lend-status --pool Prime --collateral-token ETH --borrow-token USDC
+# Check Health Factor before proceeding
+npx starkfi@latest lend-borrow \
+  --pool Prime \
+  --collateral-amount 0.1 --collateral-token ETH \
+  --borrow-amount 100 --borrow-token USDC
+npx starkfi@latest tx-status <hash>
+```
+
+**User:** "Repay my 100 USDC loan from Prime"
+
+```bash
+npx starkfi@latest lend-repay 100 --pool Prime --token USDC --collateral-token ETH
+npx starkfi@latest tx-status <hash>
+```
+
+**User:** "Close my ETH/USDC position in Prime"
+
+```bash
+npx starkfi@latest lend-close --pool Prime --collateral-token ETH --borrow-token USDC
+npx starkfi@latest tx-status <hash>
+```
+
+**User:** "How healthy is my position?"
+
+```bash
+npx starkfi@latest lend-status --pool Prime --collateral-token ETH --borrow-token USDC
+```
+
+## Error Handling
+
+| Error                     | Action                                                        |
+| ------------------------- | ------------------------------------------------------------- |
+| `Pool not found`          | Run `lend-pools` to list valid pool names.                    |
+| `Health Factor too low`   | Warn of liquidation risk. Suggest repaying or supplying more. |
+| `Insufficient collateral` | Cannot borrow without supplying first.                        |
+| `Dust limit`              | Amount is below the pool's minimum dollar value. Increase it. |
+| `Insufficient balance`    | Check `balance` — user may need to swap for the token.        |
+| `Not authenticated`       | Run `authenticate-wallet` skill first.                        |
+
+## Related Skills
+
+- Use `balance` to verify available assets before supplying.
+- Use `trade` to swap tokens if the user doesn't have the right asset.
+- Use `portfolio` for a full overview including lending positions with USD values.
+- Use `batch` to combine supply operations with swaps or staking.

package/skills/multi-swap/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: multi-swap
+description: Execute multiple token swaps in a single Starknet transaction using Fibrous aggregation. Supports 2-3 swap pairs bundled into one multicall. Use this skill when the user wants to swap multiple token pairs at once, do batch swaps, or execute several trades simultaneously in one transaction.
+license: MIT
+compatibility: Requires Node.js 18+ and npx.
+metadata:
+    version: 0.1.0
+    author: ahmetenesdur
+    category: transaction
+allowed-tools:
+    - Bash(npx starkfi@latest multi-swap *)
+    - Bash(npx starkfi@latest status)
+    - Bash(npx starkfi@latest balance)
+    - Bash(npx starkfi@latest balance *)
+    - Bash(npx starkfi@latest tx-status *)
+---
+
+# Multi-Swap
+
+Execute 2-3 independent token swaps in a single Starknet transaction via Fibrous aggregation. All swaps are bundled into one multicall, saving gas compared to executing them individually.
+
+## Prerequisites
+
+- Active session required.
+- Sufficient balance for ALL source tokens + gas fees.
+
+## Rules
+
+1. BEFORE any multi-swap, you MUST run `npx starkfi@latest status` and `npx starkfi@latest balance` to verify connectivity and source token balances for ALL pairs.
+2. Minimum **2** and maximum **3** swap pairs per multi-swap. Single swaps should use the `trade` skill instead.
+3. The pairs string MUST be wrapped in **double quotes** and each pair separated by a **comma**.
+4. Each pair follows the format: `<amount> <FROM>><TO>` (no spaces around `>`).
+5. Default slippage is **1%**. To change, use `--slippage <percent>`.
+6. Suggest using `--simulate` first so the user can confirm gas cost.
+7. AFTER a successful multi-swap, you MUST verify using `npx starkfi@latest tx-status <hash>`.
+
+## Commands
+
+```bash
+npx starkfi@latest multi-swap "<pairs>" [--slippage <percent>] [--simulate] [--json]
+```
+
+## Parameters
+
+| Parameter    | Type   | Description                                            | Required |
+| ------------ | ------ | ------------------------------------------------------ | -------- |
+| `pairs`      | string | Swap pairs: `"100 USDC>ETH, 50 USDT>STRK"` (2-3 pairs) | Yes      |
+| `--slippage` | number | Slippage tolerance in % (default: `1`)                 | No       |
+| `--simulate` | flag   | Estimate fees without broadcasting                     | No       |
+| `--json`     | flag   | Output as JSON                                         | No       |
+
+## Pair Format
+
+```
+"<amount> <FROM>><TO>, <amount> <FROM>><TO>"
+```
+
+Examples:
+
+- `"100 USDC>ETH, 200 USDT>STRK"` — two pairs
+- `"50 DAI>ETH, 100 USDC>STRK, 0.1 ETH>USDT"` — three pairs (maximum)
+
+## Examples
+
+**User:** "Swap 100 USDC to ETH and 200 USDT to STRK in one transaction"
+
+```bash
+npx starkfi@latest status
+npx starkfi@latest balance
+npx starkfi@latest multi-swap "100 USDC>ETH, 200 USDT>STRK"
+npx starkfi@latest tx-status <hash>
+```
+
+**User:** "Simulate swapping 50 DAI, 100 USDC, and 0.1 ETH"
+
+```bash
+npx starkfi@latest multi-swap "50 DAI>ETH, 100 USDC>STRK, 0.1 ETH>USDT" --simulate
+```
+
+## Error Handling
+
+| Error                  | Action                                                         |
+| ---------------------- | -------------------------------------------------------------- |
+| `Too few pairs`        | Multi-swap requires at least 2 pairs. Use `trade` for singles. |
+| `Too many pairs`       | Maximum 3 pairs. Split into multiple calls.                    |
+| `No route found`       | One or more pairs lack liquidity.                              |
+| `Insufficient balance` | Check `balance` — user may lack one of the source tokens.      |
+| `Simulation failed`    | One of the routes is invalid or would revert.                  |
+| `Not authenticated`    | Run `authenticate-wallet` skill first.                         |
+
+## Related Skills
+
+- Use `trade` for a single swap (simpler syntax).
+- Use `batch` for combining swaps with other operations (stake, supply, send).
+- Use `balance` to verify you have enough of all source tokens.

package/skills/portfolio/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: portfolio
+description: View a comprehensive DeFi portfolio dashboard — token balances, staking positions, and lending positions with USD valuations. Use this skill when the user wants an overview, summary, total value, net worth, or wants to see all their positions across Starknet at once.
+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 portfolio)
+    - Bash(npx starkfi@latest portfolio *)
+    - Bash(npx starkfi@latest status)
+---
+
+# Portfolio Overview
+
+Display a comprehensive DeFi portfolio dashboard aggregating token balances, staking positions, and lending positions — all with USD valuations. This is a read-only, single-command skill that provides a complete snapshot of the user's Starknet DeFi activity.
+
+## Prerequisites
+
+- Active session required.
+
+## Rules
+
+1. Use this as the FIRST command when the user asks "what do I have?" or wants an overall assessment.
+2. This is a read-only operation — it never modifies any on-chain state.
+3. USD prices are sourced from Fibrous aggregation and may have slight variations.
+
+## Commands
+
+```bash
+npx starkfi@latest portfolio [--json]
+```
+
+## Parameters
+
+| Parameter | Type | Description    | Required |
+| --------- | ---- | -------------- | -------- |
+| `--json`  | flag | Output as JSON | No       |
+
+## Dashboard Sections
+
+The portfolio displays three sections:
+
+1. **Token Balances** — STRK, ETH, and all ERC-20 tokens with non-zero balances and their USD values.
+2. **Staking Positions** — Active stakes across all validators/pools with pending rewards.
+3. **Lending Positions** — Active Vesu V2 positions: supplied and borrowed amounts with pool details.
+
+## Examples
+
+**User:** "Show me my portfolio"
+
+```bash
+npx starkfi@latest portfolio
+```
+
+**User:** "What's my total value on Starknet?"
+
+```bash
+npx starkfi@latest portfolio
+```
+
+**User:** "Get my portfolio as JSON for analysis"
+
+```bash
+npx starkfi@latest portfolio --json
+```
+
+## Error Handling
+
+| Error               | Action                                                                                             |
+| ------------------- | -------------------------------------------------------------------------------------------------- |
+| `Not authenticated` | Run `authenticate-wallet` skill first.                                                             |
+| `Partial failure`   | Some sections may show errors while others succeed. The portfolio uses fault-tolerant aggregation. |
+| `Network error`     | Retry once. Use `config` to set custom RPC.                                                        |
+
+## Related Skills
+
+- Use `balance` for a focused view of token balances only.
+- Use `staking` `stake-status` for detailed staking positions.
+- Use `lending` `lend-status` for detailed lending positions.

package/skills/send/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: send
+description: Send STRK, ETH, or any ERC-20 token to a Starknet address. Supports simulation (dry-run) before execution. Use this skill when the user wants to transfer, send, or move tokens to another wallet address.
+license: MIT
+compatibility: Requires Node.js 18+ and npx.
+metadata:
+    version: 0.1.0
+    author: ahmetenesdur
+    category: transaction
+allowed-tools:
+    - Bash(npx starkfi@latest send *)
+    - Bash(npx starkfi@latest status)
+    - Bash(npx starkfi@latest balance)
+    - Bash(npx starkfi@latest balance *)
+    - Bash(npx starkfi@latest tx-status *)
+---
+
+# Send Transaction
+
+Transfer STRK, ETH, or ERC-20 tokens to a destination Starknet address. The CLI automatically checks balance before sending and validates the recipient address. Supports simulation (dry-run) mode to estimate fees without broadcasting.
+
+## Prerequisites
+
+- Active session required.
+- Sufficient balance for the transfer amount + gas fees.
+
+## Rules
+
+1. BEFORE any send, you MUST run `npx starkfi@latest status` and `npx starkfi@latest balance` to verify connectivity and funds.
+2. If the recipient address was NOT previously mentioned in the conversation, you MUST ask for explicit confirmation: _"Sending [amount] [token] to [address]. Confirm?"_
+3. Suggest using `--simulate` first for large amounts so the user can review the estimated fee before committing.
+4. AFTER a successful send, you MUST verify the transaction using `npx starkfi@latest tx-status <hash>`.
+5. Starknet addresses start with `0x` and can be up to 66 characters long (including the `0x` prefix).
+
+## Commands
+
+```bash
+npx starkfi@latest send <amount> <token> <recipient> [--simulate] [--json]
+```
+
+## Parameters
+
+| Parameter    | Type   | Description                               | Required |
+| ------------ | ------ | ----------------------------------------- | -------- |
+| `amount`     | number | Amount to send (e.g. `10`, `0.5`)         | Yes      |
+| `token`      | string | Token symbol (e.g. `STRK`, `ETH`, `USDC`) | Yes      |
+| `recipient`  | string | Destination Starknet address (`0x...`)    | Yes      |
+| `--simulate` | flag   | Estimate fees without broadcasting        | No       |
+| `--json`     | flag   | Output as JSON                            | No       |
+
+## Examples
+
+**User:** "Send 10 STRK to 0x04a3..."
+
+```bash
+npx starkfi@latest status
+npx starkfi@latest balance --token STRK
+# Confirm recipient with user if needed
+npx starkfi@latest send 10 STRK 0x04a3...
+npx starkfi@latest tx-status <hash>
+```
+
+**User:** "Simulate sending 100 USDC to 0x07b2..."
+
+```bash
+npx starkfi@latest send 100 USDC 0x07b2... --simulate
+```
+
+## Error Handling
+
+| Error                  | Action                                                   |
+| ---------------------- | -------------------------------------------------------- |
+| `Insufficient balance` | Inform user of current balance via `balance`.            |
+| `Invalid address`      | Validate recipient is a valid `0x` Starknet address.     |
+| `Simulation failed`    | Transaction would revert — check amount, token, and gas. |
+| `Not authenticated`    | Run `authenticate-wallet` skill first.                   |
+
+## Related Skills
+
+- Use `balance` to verify funds before sending.
+- Use `config` to set a custom RPC if experiencing rate limits.
+- Use `trade` if the user needs to swap tokens before sending.