starkfi 0.1.0 → 0.2.0

package/skills/staking/SKILL.md

@@ -0,0 +1,188 @@
+---
+name: staking
+description: Stake, unstake, claim, and compound rewards for STRK, WBTC, tBTC, SolvBTC, and LBTC on Starknet. View validators, pools, and staking positions. Use this skill when the user mentions staking, delegating, validators, rewards, compounding, unstaking, or wants to earn yield on their STRK or BTC tokens.
+license: MIT
+compatibility: Requires Node.js 18+ and npx.
+metadata:
+    version: 0.1.0
+    author: ahmetenesdur
+    category: transaction
+allowed-tools:
+    - Bash(npx starkfi@latest validators)
+    - Bash(npx starkfi@latest validators *)
+    - Bash(npx starkfi@latest pools *)
+    - Bash(npx starkfi@latest stake-status)
+    - Bash(npx starkfi@latest stake-status *)
+    - Bash(npx starkfi@latest stake *)
+    - Bash(npx starkfi@latest unstake *)
+    - Bash(npx starkfi@latest rewards *)
+    - Bash(npx starkfi@latest status)
+    - Bash(npx starkfi@latest balance)
+    - Bash(npx starkfi@latest balance *)
+    - Bash(npx starkfi@latest tx-status *)
+---
+
+# Staking
+
+Manage Starknet staking operations: delegate tokens to validators, claim or compound rewards, and unstake positions. Supports multiple token types across various validators and pools.
+
+## Prerequisites
+
+- Active session required.
+- Sufficient token balance for staking + gas fees.
+
+## Supported Tokens
+
+| Token   | Type    |
+| ------- | ------- |
+| STRK    | Native  |
+| WBTC    | Bitcoin |
+| tBTC    | Bitcoin |
+| SolvBTC | Bitcoin |
+| LBTC    | Bitcoin |
+
+## Rules
+
+1. BEFORE staking, you MUST run `npx starkfi@latest validators` to list available validators, then `npx starkfi@latest pools <validator>` to see available pools.
+2. BEFORE staking, check `balance` to confirm the user has enough tokens.
+3. Unstaking is a **two-step process**: first `unstake intent` starts a cooldown, then `unstake exit` finalizes after the cooldown period. The user must wait between these steps.
+4. `rewards --compound` atomically claims and restakes in one transaction.
+5. AFTER any transactional operation (stake, unstake, rewards), verify with `tx-status`.
+6. Use `stake-status` to view the user's current staking positions across all validators.
+7. Token defaults to `STRK` if `--token` is not specified.
+
+## Commands
+
+```bash
+# Discovery
+npx starkfi@latest validators [--json]
+npx starkfi@latest pools <validator> [--json]
+npx starkfi@latest stake-status [validator] [--json]
+
+# Stake tokens
+npx starkfi@latest stake <amount> --validator <name> [--token <symbol>] [--simulate]
+
+# Unstake (two-step)
+npx starkfi@latest unstake intent --validator <name> --amount <amount> [--token <symbol>]
+npx starkfi@latest unstake exit --validator <name> [--token <symbol>]
+
+# Rewards
+npx starkfi@latest rewards --claim --validator <name> [--token <symbol>]
+npx starkfi@latest rewards --compound --validator <name> [--token <symbol>]
+```
+
+## Parameters
+
+### stake
+
+| Parameter     | Type   | Description                                      | Required |
+| ------------- | ------ | ------------------------------------------------ | -------- |
+| `amount`      | number | Amount to stake (positional)                     | Yes      |
+| `--validator` | string | Validator name (from `validators` list)          | Yes\*    |
+| `--pool`      | string | Pool contract address (alternative to validator) | Yes\*    |
+| `--token`     | string | Token symbol (default: `STRK`)                   | No       |
+| `--simulate`  | flag   | Estimate fees without broadcasting               | No       |
+
+\*Provide either `--validator` or `--pool`.
+
+### unstake
+
+| Parameter     | Type   | Description                               | Required   |
+| ------------- | ------ | ----------------------------------------- | ---------- |
+| action        | string | `intent` or `exit` (positional)           | Yes        |
+| `--validator` | string | Validator name                            | Yes\*      |
+| `--pool`      | string | Pool contract address                     | Yes\*      |
+| `--amount`    | number | Amount to unstake (required for `intent`) | For intent |
+| `--token`     | string | Token symbol (default: `STRK`)            | No         |
+
+### rewards
+
+| Parameter     | Type   | Description                    | Required |
+| ------------- | ------ | ------------------------------ | -------- |
+| `--claim`     | flag   | Claim pending rewards          | Yes\*    |
+| `--compound`  | flag   | Claim and immediately restake  | Yes\*    |
+| `--validator` | string | Validator name                 | Yes\*\*  |
+| `--pool`      | string | Pool contract address          | Yes\*\*  |
+| `--token`     | string | Token symbol (default: `STRK`) | No       |
+
+\*Provide either `--claim` or `--compound`. \*\*Provide either `--validator` or `--pool`.
+
+## Examples
+
+**User:** "Which validators can I stake with?"
+
+```bash
+npx starkfi@latest validators
+```
+
+**User:** "Show me pools for Juno"
+
+```bash
+npx starkfi@latest pools Juno
+```
+
+**User:** "Stake 1000 STRK with Juno"
+
+```bash
+npx starkfi@latest status
+npx starkfi@latest balance --token STRK
+npx starkfi@latest stake 1000 --validator Juno
+npx starkfi@latest tx-status <hash>
+```
+
+**User:** "Stake 0.5 WBTC with Karnot"
+
+```bash
+npx starkfi@latest balance --token WBTC
+npx starkfi@latest stake 0.5 --validator Karnot --token WBTC
+npx starkfi@latest tx-status <hash>
+```
+
+**User:** "Compound my STRK rewards from Juno"
+
+```bash
+npx starkfi@latest rewards --compound --validator Juno
+npx starkfi@latest tx-status <hash>
+```
+
+**User:** "Claim my rewards from Karnot"
+
+```bash
+npx starkfi@latest rewards --claim --validator Karnot
+npx starkfi@latest tx-status <hash>
+```
+
+**User:** "I want to unstake my STRK from Juno"
+
+```bash
+# Step 1: Start unstake cooldown
+npx starkfi@latest unstake intent --validator Juno --amount 1000
+npx starkfi@latest tx-status <hash>
+# Inform user about cooldown period
+# Step 2: After cooldown, finalize
+npx starkfi@latest unstake exit --validator Juno
+npx starkfi@latest tx-status <hash>
+```
+
+**User:** "Show me all my staking positions"
+
+```bash
+npx starkfi@latest stake-status
+```
+
+## Error Handling
+
+| Error                   | Action                                           |
+| ----------------------- | ------------------------------------------------ |
+| `Validator not found`   | Run `validators` to list valid names.            |
+| `Pool not found`        | Run `pools <validator>` to list available pools. |
+| `Insufficient balance`  | Check `balance` and suggest a smaller amount.    |
+| `Cooldown not complete` | User must wait before running `unstake exit`.    |
+| `No rewards to claim`   | Position has no pending rewards.                 |
+| `Not authenticated`     | Run `authenticate-wallet` skill first.           |
+
+## Related Skills
+
+- Use `balance` to check available tokens before staking.
+- Use `portfolio` for a full overview including staking positions with USD values.
+- Use `batch` to combine staking with other operations in one transaction.

package/skills/trade/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: trade
+description: Swap tokens on Starknet using Fibrous aggregation for optimal routing. Supports simulation (dry-run) before execution. Use this skill when the user wants to swap, exchange, trade, convert, or buy one token with another on Starknet.
+license: MIT
+compatibility: Requires Node.js 18+ and npx.
+metadata:
+    version: 0.1.0
+    author: ahmetenesdur
+    category: transaction
+allowed-tools:
+    - Bash(npx starkfi@latest trade *)
+    - Bash(npx starkfi@latest status)
+    - Bash(npx starkfi@latest balance)
+    - Bash(npx starkfi@latest balance *)
+    - Bash(npx starkfi@latest tx-status *)
+---
+
+# Trade / Swap Tokens
+
+Exchange one token for another on Starknet via Fibrous trade aggregation. The CLI finds the best route across multiple DEXs, simulates the swap, and executes. All transactions are routed through the Paymaster by default (gas paid in STRK or configured token).
+
+## Prerequisites
+
+- Active session required.
+- Sufficient balance of the source token + gas fees.
+
+## Rules
+
+1. BEFORE any trade, you MUST run `npx starkfi@latest status` and `npx starkfi@latest balance` to verify connectivity and source token balance.
+2. Default slippage is **1%**. To change, use `--slippage <percent>`.
+3. Suggest using `--simulate` first for large trades so the user can review the estimated fee and expected output before committing.
+4. AFTER a successful trade, you MUST verify the transaction using `npx starkfi@latest tx-status <hash>`.
+5. For **multiple swaps in one transaction**, use the `multi-swap` skill instead.
+
+## Commands
+
+```bash
+npx starkfi@latest trade <amount> <from> <to> [--slippage <percent>] [--simulate] [--json]
+```
+
+## Parameters
+
+| Parameter    | Type   | Description                              | Required |
+| ------------ | ------ | ---------------------------------------- | -------- |
+| `amount`     | number | Amount of source token to swap           | Yes      |
+| `from`       | string | Source token symbol (e.g. `ETH`, `USDC`) | Yes      |
+| `to`         | string | Target token symbol (e.g. `STRK`, `DAI`) | Yes      |
+| `--slippage` | number | Slippage tolerance in % (default: `1`)   | No       |
+| `--simulate` | flag   | Estimate fees without broadcasting       | No       |
+| `--json`     | flag   | Output as JSON                           | No       |
+
+## Examples
+
+**User:** "Swap 100 USDC for ETH"
+
+```bash
+npx starkfi@latest status
+npx starkfi@latest balance --token USDC
+npx starkfi@latest trade 100 USDC ETH
+npx starkfi@latest tx-status <hash>
+```
+
+**User:** "How much ETH would I get for 500 USDC?"
+
+```bash
+npx starkfi@latest trade 500 USDC ETH --simulate
+```
+
+**User:** "Convert 0.5 ETH to STRK with 2% slippage"
+
+```bash
+npx starkfi@latest status
+npx starkfi@latest balance --token ETH
+npx starkfi@latest trade 0.5 ETH STRK --slippage 2
+npx starkfi@latest tx-status <hash>
+```
+
+## Error Handling
+
+| Error                  | Action                                                  |
+| ---------------------- | ------------------------------------------------------- |
+| `No route found`       | Liquidity may be too low or pair doesn't exist.         |
+| `Insufficient balance` | Check `balance` and suggest a smaller amount.           |
+| `Simulation failed`    | Route is invalid or would revert. Do not retry blindly. |
+| `Not authenticated`    | Run `authenticate-wallet` skill first.                  |
+
+## Related Skills
+
+- Use `balance` to check available tokens before trading.
+- Use `multi-swap` for executing 2-3 swaps in a single transaction.
+- Use `batch` for combining a swap with other operations (stake, supply, send).
+- Use `config` to set a custom RPC if experiencing rate limits.