starkfi 0.4.2 → 0.4.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/MCP.md +1 -1
  2. package/README.md +88 -54
  3. package/dist/index.js +69 -69
  4. package/package.json +1 -1
  5. package/skills/batch/SKILL.md +4 -3
package/MCP.md CHANGED
@@ -279,7 +279,7 @@ Views and modifies global CLI behavior: RPC routing, network selection, and Gas
279
279
  | Parameter | Type | Required | Description |
280
280
  | --------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
281
281
  | `action` | enum | **Yes** | One of: `list`, `reset`, `set-rpc`, `get-rpc`, `set-network`, `set-gasfree`, `set-gas-token` |
282
- | `value` | string | No | `set-gasfree`: `on`/`off`. `set-gas-token`: symbol (`USDC`, `ETH`) or `reset`. `set-rpc`: URL string. `set-network`: `mainnet`/`sepolia`. |
282
+ | `value` | string | No | `set-gasfree`: `on`/`off`. `set-gas-token`: symbol (`USDC`, `ETH`) or `reset`/`off`. `set-rpc`: URL string. `set-network`: `mainnet`/`sepolia`. |
283
283
 
284
284
  ---
285
285
 
package/README.md CHANGED
@@ -1,14 +1,11 @@
1
1
  <p align="center">
2
2
  <a href="https://starkfi.app">
3
- <img src="landing/favicon.svg" alt="StarkFi Logo" width="100" height="100"/>
3
+ <img src="landing/readme-banner.png" alt="StarkFi — The AI-native DeFi toolkit for Starknet" width="100%" />
4
4
  </a>
5
5
  </p>
6
6
 
7
- <h1 align="center">StarkFi</h1>
8
-
9
7
  <p align="center">
10
- <strong>The AI-native DeFi toolkit for Starknet.</strong><br>
11
- A production-grade CLI and MCP server that gives both developers and AI agents full access to swaps, multi-swap, atomic batch transactions, staking, lending, portfolio management, and gasless transactions — all powered by the <a href="https://github.com/keep-starknet-strange/starkzap">Starkzap SDK</a>.
8
+ A production-grade CLI, MCP server, and Telegram bot that gives both developers and AI agents full access to swaps, multi-swap, atomic batch transactions, staking, lending, portfolio management, and gasless transactions — all powered by the <a href="https://github.com/keep-starknet-strange/starkzap">Starkzap SDK</a>.
12
9
  </p>
13
10
 
14
11
  <p align="center">
@@ -31,42 +28,43 @@ Most DeFi tools are built for humans clicking buttons. StarkFi is built for **ag
31
28
  - 💸 **Gas Abstraction Built-In** — Pay gas in STRK, ETH, USDC, USDT, or DAI via AVNU Paymaster, or let the developer sponsor gas entirely (gasfree mode)
32
29
  - 📊 **Full Portfolio** — Unified view of balances, staking positions, and lending positions with USD values
33
30
  - 🧪 **Simulate Everything** — Dry-run any transaction to estimate fees before broadcasting
31
+ - 💬 **Telegram Bot** — Chat-based DeFi via natural language, BYOAI model (OpenAI, Claude, Gemini)
34
32
 
35
33
  ---
36
34
 
37
35
  ## Architecture
38
36
 
39
37
  ```
40
- ┌──────────────────────────────────────────────────────────────────────────┐
41
- │ StarkFi │
42
- │ │
43
- │ ┌──────────┐ ┌─────────────────────┐ ┌───────────────────────┐ │
44
- │ │ CLI │ │ MCP Server │ │ Agent Skills │ │
45
- │ │ (30+ │ │ (27 tools) │ │ (10 workflows) │ │
46
- │ │ commands)│ │ stdio transport │ │ npx starkfi@latest │ │
47
- │ └────┬─────┘ └──────────┬──────────┘ └──────────┬────────────┘ │
48
- │ │ │ │ │
49
- │ └──────────────────────┼───────────────────────────┘ │
50
- │ ▼ │
51
- │ ┌──────────────────────────────────────────────────────────────────┐ │
52
- │ │ Service Layer │ │
53
- │ │ ┌──────────┐ ┌──────────┐ ┌────────┐ ┌──────────┐ │ │
54
- │ │ │ Fibrous │ │ Staking │ │ Vesu │ │ Batch │ │ │
55
- │ │ │ Swap │ │ Lifecycle│ │ V2 │ │ Multicall│ │ │
56
- │ │ └────┬─────┘ └────┬─────┘ └───┬────┘ └────┬─────┘ │ │
57
- │ │ └─────────────┴────────────┴────────────┘ │ │
58
- │ │ │ │ │
59
- │ │ ┌───────────────┴───────────────────────────┐ │ │
60
- │ │ │ Starkzap SDK (starkzap v1.0.0) │ │ │
61
- │ │ │ Wallet · TxBuilder · Tokens · Paymaster │ │ │
62
- │ │ └───────────────┬───────────────────────────┘ │ │
63
- │ └───────────────────────┼──────────────────────────────────────────┘ │
64
- │ ▼ │
65
- │ ┌──────────────────────────────────────┐ ┌──────────────────────┐ │
66
- │ │ Auth Server (Hono + Privy TEE) │ │ AVNU Paymaster │ │
67
- │ │ Email OTP · Wallet · Sign · Gas │ │ Gas Abstraction │ │
68
- │ └──────────────────────────────────────┘ └──────────────────────┘ │
69
- └──────────────────────────────────────────────────────────────────────────┘
38
+ ┌─────────────────────────────────────────────────────────────────────────────────────┐
39
+ │ StarkFi │
40
+ │ │
41
+ │ ┌──────────┐ ┌────────────────┐ ┌────────────────┐ ┌─────────────────────────┐ │
42
+ │ │ CLI │ │ MCP Server │ │ Agent Skills │ │ Telegram Bot │ │
43
+ │ │ (30+ │ │ (27 tools) │ │ (10 workflows) │ │ (BYOAI · Chat DeFi) │ │
44
+ │ │ commands)│ │ stdio transport│ │ npx starkfi │ │ OpenAI / Claude / │ │
45
+ │ └────┬─────┘ └──────┬─────────┘ └─────┬──────────┘ │ Gemini │ │
46
+ │ │ │ │ └───────────┬─────────────┘ │
47
+ │ └───────────────┼──────────────────┼─────────────────────────┘ │
48
+ │ ▼ ▼ │
49
+ │ ┌──────────────────────────────────────────────────────────────────────────────┐ │
50
+ │ │ Service Layer │ │
51
+ │ │ ┌──────────┐ ┌──────────┐ ┌────────┐ ┌──────────┐ ┌──────────────┐ │ │
52
+ │ │ │ Fibrous │ │ Staking │ │ Vesu │ │ Batch │ │ Portfolio │ │ │
53
+ │ │ │ Swap │ │ Lifecycle│ │ V2 │ │ Multicall│ │ Dashboard │ │ │
54
+ │ │ └────┬─────┘ └────┬─────┘ └───┬────┘ └────┬─────┘ └──────┬───────┘ │ │
55
+ │ │ └─────────────┴────────────┴────────────┴───────────────┘ │ │
56
+ │ │ │ │ │
57
+ │ │ ┌───────────────┴───────────────────────────┐ │ │
58
+ │ │ │ Starkzap SDK (starkzap v1.0.0) │ │ │
59
+ │ │ │ Wallet · TxBuilder · Tokens · Paymaster │ │ │
60
+ │ │ └───────────────┬───────────────────────────┘ │ │
61
+ │ └───────────────────────┼──────────────────────────────────────────────────────┘ │
62
+ │ ▼ │
63
+ │ ┌──────────────────────────────────────┐ ┌──────────────────────┐ │
64
+ │ │ Auth Server (Hono + Privy TEE) │ │ AVNU Paymaster │ │
65
+ │ │ Email OTP · Wallet · Sign · Gas │ │ Gas Abstraction │ │
66
+ │ └──────────────────────────────────────┘ └──────────────────────┘ │
67
+ └─────────────────────────────────────────────────────────────────────────────────────┘
70
68
  │
71
69
  ▼
72
70
  ┌──────────────────┐
@@ -314,22 +312,22 @@ npx starkfi@latest trade 10 STRK ETH # Execute
314
312
  | ----------------------------------------------------------------------------- | ---------------------- |
315
313
  | `validators [--json]` | List active validators |
316
314
  | `pools <validator> [--json]` | Show delegation pools |
317
- | `stake <amount> --validator <name> [--token <symbol>] [--simulate] [--json]` | Stake tokens |
315
+ | `stake <amount> --validator <name> [--token <symbol>] [--simulate] [--json]` | Stake tokens |
318
316
  | `stake-status [validator] [--json]` | Staking dashboard |
319
317
  | `rewards --validator <name> [--token <symbol>] <--claim\|--compound>` | Manage rewards |
320
318
  | `unstake <intent\|exit> --validator <name> [--token <symbol>] [--amount <n>]` | Unstake (2-step) |
321
319
 
322
320
  ### Lending (Vesu V2)
323
321
 
324
- | Command | Description |
325
- | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------- |
326
- | `lend-pools [name]` | List lending pools |
327
- | `lend-supply <amount> -p <pool> -t <token>` | Supply assets |
328
- | `lend-withdraw <amount> -p <pool> -t <token>` | Withdraw assets |
329
- | `lend-borrow -p <pool> --collateral-amount <n> --collateral-token <t> --borrow-amount <n> --borrow-token <t> [--use-supplied]` | Borrow |
330
- | `lend-repay <amount> -p <pool> -t <token> --collateral-token <t>` | Repay debt |
322
+ | Command | Description |
323
+ | ------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------- |
324
+ | `lend-pools [name]` | List lending pools |
325
+ | `lend-supply <amount> -p <pool> -t <token>` | Supply assets |
326
+ | `lend-withdraw <amount> -p <pool> -t <token>` | Withdraw assets |
327
+ | `lend-borrow -p <pool> --collateral-amount <n> --collateral-token <t> --borrow-amount <n> --borrow-token <t> [--use-supplied]` | Borrow |
328
+ | `lend-repay <amount> -p <pool> -t <token> --collateral-token <t>` | Repay debt |
331
329
  | `lend-status [-p <pool> --collateral-token <t> [--borrow-token <t>]]` | Position status (auto-scan if no args) |
332
- | `lend-close -p <pool> --collateral-token <t> --borrow-token <t>` | Close position atomically |
330
+ | `lend-close -p <pool> --collateral-token <t> --borrow-token <t>` | Close position atomically |
333
331
 
334
332
  ### Configuration
335
333
 
@@ -371,6 +369,33 @@ See [`server/README.md`](server/README.md) for setup instructions.
371
369
 
372
370
  ---
373
371
 
372
+ ## Telegram Bot
373
+
374
+ StarkFi has a dedicated **[Telegram bot](https://github.com/ahmetenesdur/starkfi-telegram-bot)** that brings DeFi to chat. Users interact with natural language — the bot translates commands into StarkFi operations.
375
+
376
+ **BYOAI Model** — each user provides their own API key (OpenAI, Claude, or Gemini). No shared keys, no centralized billing.
377
+
378
+ | Feature | Description |
379
+ | ------------- | --------------------------------------------------------- |
380
+ | **Swap** | DEX-aggregated trading via Fibrous |
381
+ | **Stake** | Multi-token staking (STRK, WBTC, tBTC, SolvBTC, LBTC) |
382
+ | **Lend** | Supply, borrow, repay, withdraw, close on Vesu V2 |
383
+ | **Portfolio** | Balances with USD valuations and position health |
384
+ | **Batch** | Combine swap + stake + supply + send in one transaction |
385
+ | **Gas Modes** | Gasless (pay in ERC-20) and gasfree (developer-sponsored) |
386
+
387
+ ```bash
388
+ git clone https://github.com/ahmetenesdur/starkfi-telegram-bot.git
389
+ cd starkfi-telegram-bot
390
+ pnpm install
391
+ cp .env.example .env # Configure TELEGRAM_BOT_TOKEN, BOT_ENCRYPTION_SECRET
392
+ pnpm dev
393
+ ```
394
+
395
+ See [`starkfi-telegram-bot/`](https://github.com/ahmetenesdur/starkfi-telegram-bot) for full setup and deployment (Docker support included).
396
+
397
+ ---
398
+
374
399
  ## Tech Stack
375
400
 
376
401
  | Layer | Technology |
@@ -403,16 +428,25 @@ All network operations include **automatic retry with exponential backoff** (500
403
428
 
404
429
  ### Readable Starknet Errors
405
430
 
406
- Raw Starknet JSON-RPC errors (hex-encoded Cairo strings like `u256_sub Overflow`) are automatically parsed into human-readable messages:
407
-
408
- | Raw Error | Displayed Message |
409
- |-----------|------------------|
410
- | `u256_sub Overflow` | Insufficient balance — you don't have enough tokens (including gas fees) |
411
- | `ERC20: insufficient allowance` | Token approval required — not enough allowance for this operation |
412
- | `UNAUTHORIZED` | Unauthorized — session may have expired, try: starkfi auth login |
413
- | `argent/multicall-failed` | One or more calls in the transaction failed |
414
- | `dusty-collateral-balance` | Collateral amount is below the pool's minimum (dust limit). Please increase the amount. |
415
- | `dusty-debt-balance` | Borrow amount is below the pool's minimum (dust limit). Please increase the amount. |
431
+ Raw Starknet JSON-RPC errors (hex-encoded Cairo strings like `u256_sub Overflow`) are automatically parsed into human-readable messages (15 patterns):
432
+
433
+ | Raw Error | Displayed Message |
434
+ | ---------------------------------------- | --------------------------------------------------------------------------------------- |
435
+ | `u256_sub Overflow` | Insufficient balance — you don't have enough tokens (including gas fees) |
436
+ | `u256_add Overflow` | Amount overflow — the value is too large |
437
+ | `ERC20: transfer amount exceeds balance` | Insufficient token balance for this transfer |
438
+ | `ERC20: burn amount exceeds balance` | Insufficient token balance to burn |
439
+ | `ERC20: insufficient allowance` | Token approval required — not enough allowance for this operation |
440
+ | `argent/multicall-failed` | One or more calls in the transaction failed |
441
+ | `argent/invalid-signature` | Invalid signature — try re-authenticating with: starkfi auth login |
442
+ | `argent/invalid-timestamp` | Transaction expired — please retry |
443
+ | `is_valid_signature` | Signature validation failed — try re-authenticating |
444
+ | `assert_not_zero` | Operation failed — a required value was zero |
445
+ | `Contract not found` | Contract not found — the target contract does not exist on this network |
446
+ | `UNAUTHORIZED` | Unauthorized — session may have expired, try: starkfi auth login |
447
+ | `nonce` | Transaction nonce error — please retry |
448
+ | `dusty-collateral-balance` | Collateral amount is below the pool's minimum (dust limit). Please increase the amount. |
449
+ | `dusty-debt-balance` | Borrow amount is below the pool's minimum (dust limit). Please increase the amount. |
416
450
 
417
451
  This applies to both CLI output (`formatError`) and MCP responses (`withErrorHandling`).
418
452