starkfi 0.6.0 → 0.6.2

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 (7) hide show
  1. package/MCP.md +7 -7
  2. package/README.md +61 -102
  3. package/dist/index.js +127 -121
  4. package/package.json +6 -6
  5. package/skills/confidential/SKILL.md +19 -17
  6. package/skills/dca/SKILL.md +3 -2
  7. package/skills/portfolio/SKILL.md +3 -1
package/MCP.md CHANGED
@@ -168,7 +168,7 @@ Creates a recurring DCA order that automatically executes swaps at regular inter
168
168
 
169
169
  #### `dca_list`
170
170
 
171
- Lists the user's DCA orders with optional filtering by status and provider.
171
+ Lists the user's DCA orders with optional filtering by status and provider. Each order in the response includes both `id` (UUID) and `orderAddress` (on-chain contract address) — use either to cancel.
172
172
 
173
173
  | Parameter | Type | Required | Description |
174
174
  | ---------- | ------ | -------- | ---------------------------------------------------------- |
@@ -178,13 +178,13 @@ Lists the user's DCA orders with optional filtering by status and provider.
178
178
 
179
179
  #### `dca_cancel`
180
180
 
181
- Cancels an active DCA order. Requires either the order ID or order address.
181
+ Cancels an active DCA order. Use the order UUID or on-chain contract address from `dca_list`. At least one identifier is required.
182
182
 
183
- | Parameter | Type | Required | Description |
184
- | --------------- | ------- | -------- | --------------------------------------------------------- |
185
- | `order_id` | string | No* | DCA order ID (from `dca_list`) |
186
- | `order_address` | string | No* | DCA order contract address (`0x...`) |
187
- | `provider` | string | No | DCA provider: `avnu` or `ekubo` |
183
+ | Parameter | Type | Required | Description |
184
+ | --------------- | ------- | -------- | -------------------------------------------------------------------------- |
185
+ | `order_id` | string | No* | DCA order UUID (the `id` field from `dca_list`) |
186
+ | `order_address` | string | No* | DCA order on-chain contract address (the `orderAddress` field from `dca_list`) |
187
+ | `provider` | string | No | DCA provider: `avnu` or `ekubo` |
188
188
 
189
189
  \*At least one of `order_id` or `order_address` is required.
190
190
 
package/README.md CHANGED
@@ -32,62 +32,19 @@ Most DeFi tools are built for humans clicking buttons. StarkFi is built for **ag
32
32
 
33
33
  ---
34
34
 
35
- ## Architecture
36
-
37
- ```
38
- ┌───────────────────────────────────────────────────────────────────────────────────────┐
39
- │ StarkFi │
40
- │ │
41
- │ ┌──────────┐ ┌────────────────┐ ┌────────────────┐ ┌─────────────────────────┐ │
42
- │ │ CLI │ │ MCP Server │ │ Agent Skills │ │ Telegram Bot │ │
43
- │ │ (42+ │ │ (42 tools) │ │ (12 workflows) │ │ (BYOAI · Chat DeFi) │ │
44
-
45
- │ │ commands)│ │ stdio transport│ │ npx starkfi │ │ OpenAI / Claude / │ │
46
- │ └────┬─────┘ └──────┬─────────┘ └─────┬──────────┘ │ Gemini │ │
47
- │ │ │ │ └───────────┬─────────────┘ │
48
- │ └───────────────┼──────────────────┼─────────────────────────┘ │
49
- │ ▼ ▼ │
50
- │ ┌────────────────────────────────────────────────────────────────────────────────┐ │
51
- │ │ Service Layer │ │
52
- │ │ ┌────────┐ ┌────────┐ ┌──────┐ ┌─────┐ ┌────────┐ ┌─────────┐ ┌──────────────┐ │ │
53
- │ │ │ DEX │ │Staking │ │ Vesu │ │ DCA │ │ Batch │ │Portfolio│ │ Confidential │ │ │
54
- │ │ │ Swap │ │Lifecycl│ │ V2 │ │ │ │Multical│ │Dashboard│ │ Tongo Cash │ │ │
55
- │ │ └────┬─────┘ └────┬─────┘ └───┬────┘ └───┬──┘ └────┬─────┘ └────┬─────┘ │ │
56
- │ │ └─────────────┴────────────┴───────────┴──────────┴─────────────┘ │ │
57
- │ │ │ │ │
58
- │ │ ┌───────────┴───────────────────────────────┐ │ │
59
- │ │ │ Starkzap SDK (starkzap v2.0.0) │ │ │
60
- │ │ │ Wallet · TxBuilder · Tokens · Paymaster │ │ │
61
- │ │ └─────────────┬─────────────────────────────┘ │ │
62
- │ └───────────────────────┼────────────────────────────────────────────────────────┘ │
63
- │ ▼ │
64
- │ ┌──────────────────────────────────────┐ ┌──────────────────────┐ │
65
- │ │ Auth Server (Hono + Privy TEE) │ │ AVNU Paymaster │ │
66
- │ │ Email OTP · Wallet · Sign · Gas │ │ Gas Abstraction │ │
67
- │ └──────────────────────────────────────┘ └──────────────────────┘ │
68
- └───────────────────────────────────────────────────────────────────────────────────────┘
69
- │
70
- ▼
71
- ┌──────────────────┐
72
- │ Starknet (L2) │
73
- └──────────────────┘
74
- ```
75
-
76
- ---
77
-
78
35
  ## Starkzap Modules Used
79
36
 
80
37
  StarkFi leverages **all core Starkzap modules**:
81
38
 
82
- | Module | Usage in StarkFi |
83
- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
84
- | **Wallets** | `OnboardStrategy.Privy` + `argentXV050` preset for automated email-based wallet onboarding via Privy TEE |
85
- | **Gasless Transactions (Paymaster)** | Paymaster integration with 5 gas tokens (STRK, ETH, USDC, USDT, DAI) + developer-sponsored gasfree mode |
86
- | **Staking** | Multi-token staking lifecycle (STRK, WBTC, tBTC, SolvBTC, LBTC) — stake, claim, compound, unstake (2-step) |
87
- | **DCA** | Dollar-Cost Averaging via AVNU and Ekubo — create, preview, list, and cancel recurring buy orders |
88
- | **TxBuilder** | Atomic multicall batching — combine swap + stake + supply + send + borrow + repay + withdraw + dca in one transaction |
89
- | **Confidential (Tongo Cash)** | Privacy-preserving transfers via TongoConfidential — fund, transfer, withdraw, ragequit, rollover |
90
- | **ERC-20 Tokens** | Token presets, balance queries, transfers, approvals |
39
+ | Module | Usage in StarkFi |
40
+ | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
41
+ | **Wallets** | `OnboardStrategy.Privy` + `argentXV050` preset for automated email-based wallet onboarding via Privy TEE |
42
+ | **Gasless Transactions (Paymaster)** | Paymaster integration with 5 gas tokens (STRK, ETH, USDC, USDT, DAI) + developer-sponsored gasfree mode |
43
+ | **Staking** | Multi-token staking lifecycle (STRK, WBTC, tBTC, SolvBTC, LBTC) — stake, claim, compound, unstake (2-step) |
44
+ | **DCA** | Dollar-Cost Averaging via AVNU and Ekubo — create, preview, list, and cancel recurring buy orders |
45
+ | **TxBuilder** | Atomic multicall batching — combine swap + stake + supply + send + borrow + repay + withdraw + dca in one transaction |
46
+ | **Confidential (Tongo Cash)** | Privacy-preserving transfers via TongoConfidential — fund, transfer, withdraw, ragequit, rollover |
47
+ | **ERC-20 Tokens** | Token presets, balance queries, transfers, approvals |
91
48
 
92
49
  ---
93
50
 
@@ -187,16 +144,16 @@ npx starkfi@latest config set-network sepolia # Switch to testnet
187
144
  npx starkfi@latest config set-network mainnet # Switch back
188
145
  ```
189
146
 
190
- | Module | Network-Aware | Notes |
191
- | --------------------- | ------------- | ------------------------------------------------------------ |
192
- | **Lending (Vesu V2)** | ✅ | Pools, supply, borrow, monitor, auto-rebalance |
193
- | **Staking** | ✅ | Multi-token — STRK, WBTC, tBTC, SolvBTC, LBTC |
147
+ | Module | Network-Aware | Notes |
148
+ | --------------------- | ------------- | ------------------------------------------------------------------------ |
149
+ | **Lending (Vesu V2)** | ✅ | Pools, supply, borrow, monitor, auto-rebalance |
150
+ | **Staking** | ✅ | Multi-token — STRK, WBTC, tBTC, SolvBTC, LBTC |
194
151
  | **Batch** | ✅ | All batch operations (supply, borrow, repay, withdraw, stake, send, dca) |
195
- | **Portfolio** | ✅ | Balances, staking positions, lending positions |
196
- | **Wallet (Send)** | ✅ | Token transfers and simulation |
197
- | **Swap** | Mainnet only | Fibrous (default), AVNU, Ekubo — selectable via `--provider` |
198
- | **Multi-Swap** | Mainnet only | Per-pair provider selection |
199
- | **Rebalance** | Mainnet only | Uses swap routing for rebalance execution |
152
+ | **Portfolio** | ✅ | Balances, staking positions, lending positions |
153
+ | **Wallet (Send)** | ✅ | Token transfers and simulation |
154
+ | **Swap** | Mainnet only | Fibrous (default), AVNU, Ekubo — selectable via `--provider` |
155
+ | **Multi-Swap** | Mainnet only | Per-pair provider selection |
156
+ | **Rebalance** | Mainnet only | Uses swap routing for rebalance execution |
200
157
 
201
158
  ### 💸 Gas Abstraction
202
159
 
@@ -230,7 +187,7 @@ Consolidated view of all DeFi positions in one call.
230
187
 
231
188
  ```bash
232
189
  npx starkfi@latest portfolio
233
- # → Token Balances (USD), Staking Positions, Lending Positions, Total Value
190
+ # → Token Balances (USD), Staking Positions, Lending Positions, DCA Orders, Confidential Balance, Total Value
234
191
  ```
235
192
 
236
193
  ### 📈 Portfolio Optimization
@@ -255,16 +212,16 @@ npx starkfi@latest mcp-start
255
212
 
256
213
  ### Tool Categories
257
214
 
258
- | Category | Tools | Count |
259
- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
260
- | **Auth & Config** | `get_auth_status`, `config_action` | 2 |
261
- | **Wallet** | `get_balance`, `get_portfolio`, `deploy_account`, `send_tokens`, `get_tx_status`, `rebalance_portfolio` | 6 |
262
- | **Trade** | `get_swap_quote`, `swap_tokens`, `get_multi_swap_quote`, `multi_swap`, `batch_execute` | 5 |
263
- | **Staking** | `list_validators`, `list_pools`, `get_staking_info`, `get_stake_status`, `stake_tokens`, `unstake_tokens`, `claim_rewards`, `compound_rewards` | 8 |
264
- | **Lending** | `list_lending_pools`, `get_lending_position`, `supply_assets`, `withdraw_assets`, `borrow_assets`, `repay_debt`, `close_position`, `monitor_lending_position`, `auto_rebalance_lending` | 9 |
265
- | **DCA** | `dca_preview`, `dca_create`, `dca_list`, `dca_cancel` | 4 |
266
- | **Confidential** | `confidential_setup`, `confidential_balance`, `confidential_fund`, `confidential_transfer`, `confidential_withdraw`, `confidential_ragequit`, `confidential_rollover` | 7 |
267
- | **Health (Lending)** | `lending_quote_health` | 1 |
215
+ | Category | Tools | Count |
216
+ | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
217
+ | **Auth & Config** | `get_auth_status`, `config_action` | 2 |
218
+ | **Wallet** | `get_balance`, `get_portfolio`, `deploy_account`, `send_tokens`, `get_tx_status`, `rebalance_portfolio` | 6 |
219
+ | **Trade** | `get_swap_quote`, `swap_tokens`, `get_multi_swap_quote`, `multi_swap`, `batch_execute` | 5 |
220
+ | **Staking** | `list_validators`, `list_pools`, `get_staking_info`, `get_stake_status`, `stake_tokens`, `unstake_tokens`, `claim_rewards`, `compound_rewards` | 8 |
221
+ | **Lending** | `list_lending_pools`, `get_lending_position`, `supply_assets`, `withdraw_assets`, `borrow_assets`, `repay_debt`, `close_position`, `monitor_lending_position`, `auto_rebalance_lending` | 9 |
222
+ | **DCA** | `dca_preview`, `dca_create`, `dca_list`, `dca_cancel` | 4 |
223
+ | **Confidential** | `confidential_setup`, `confidential_balance`, `confidential_fund`, `confidential_transfer`, `confidential_withdraw`, `confidential_ragequit`, `confidential_rollover` | 7 |
224
+ | **Health (Lending)** | `lending_quote_health` | 1 |
268
225
 
269
226
  ### Example — AI Agent Workflow
270
227
 
@@ -385,20 +342,20 @@ npx starkfi@latest trade 10 STRK ETH # Execute
385
342
 
386
343
  ### Confidential Transfers (Tongo Cash)
387
344
 
388
- | Command | Description |
389
- | ------------------------------------------------------------------------------ | ------------------------------------ |
390
- | `conf-setup --key <key> --contract <address>` | Configure Tongo Cash credentials |
391
- | `conf-balance [--json]` | Show confidential balance |
392
- | `conf-fund <amount> [--token <symbol>] [--simulate] [--json]` | Fund confidential account |
393
- | `conf-transfer <amount> --recipient-x <x> --recipient-y <y> [--simulate] [--json]` | Confidential transfer |
394
- | `conf-withdraw <amount> [--to <address>] [--token <symbol>] [--simulate] [--json]` | Withdraw to public address |
395
- | `conf-ragequit [--to <address>] [--json]` | Emergency full withdrawal |
396
- | `conf-rollover [--json]` | Activate pending balance |
345
+ | Command | Description |
346
+ | ---------------------------------------------------------------------------------- | -------------------------------- |
347
+ | `conf-setup --key <key> --contract <address>` | Configure Tongo Cash credentials |
348
+ | `conf-balance [--json]` | Show confidential balance |
349
+ | `conf-fund <amount> [--token <symbol>] [--simulate] [--json]` | Fund confidential account |
350
+ | `conf-transfer <amount> --recipient-x <x> --recipient-y <y> [--simulate] [--json]` | Confidential transfer |
351
+ | `conf-withdraw <amount> [--to <address>] [--token <symbol>] [--simulate] [--json]` | Withdraw to public address |
352
+ | `conf-ragequit [--to <address>] [--json]` | Emergency full withdrawal |
353
+ | `conf-rollover [--json]` | Activate pending balance |
397
354
 
398
355
  ### Batching (Multicall)
399
356
 
400
- | Command | Description |
401
- | --------------------------------------------------------------------------- | ---------------------------- |
357
+ | Command | Description |
358
+ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- |
402
359
  | `batch [--simulate] --swap "..." --stake "..." --supply "..." --send "..." --borrow "..." --repay "..." --withdraw "..." --dca-create "..." --dca-cancel "..."` | Atomic multicall (min 2 ops) |
403
360
 
404
361
  ### Staking
@@ -479,16 +436,16 @@ StarkFi has a dedicated **[Telegram bot](https://github.com/ahmetenesdur/starkfi
479
436
 
480
437
  **BYOAI Model** — each user provides their own API key (OpenAI, Claude, or Gemini). No shared keys, no centralized billing.
481
438
 
482
- | Feature | Description |
483
- | ----------------- | ------------------------------------------------------------------- |
484
- | **Swap** | Token trading via Fibrous (default), AVNU, or Ekubo |
485
- | **Stake** | Multi-token staking (STRK, WBTC, tBTC, SolvBTC, LBTC) |
486
- | **Lend** | Supply, borrow, repay, withdraw, close on Vesu V2 |
487
- | **DCA** | Dollar-Cost Averaging with recurring buy orders (AVNU, Ekubo) |
488
- | **Confidential** | Privacy-preserving transfers via Tongo Cash (ZK proofs) |
489
- | **Portfolio** | Balances with USD valuations and position health |
490
- | **Batch** | Combine swap + stake + supply + send + borrow + repay + withdraw + DCA in one transaction |
491
- | **Gas Modes** | Gasless (pay in ERC-20) and gasfree (developer-sponsored) |
439
+ | Feature | Description |
440
+ | ---------------- | ----------------------------------------------------------------------------------------- |
441
+ | **Swap** | Token trading via Fibrous (default), AVNU, or Ekubo |
442
+ | **Stake** | Multi-token staking (STRK, WBTC, tBTC, SolvBTC, LBTC) |
443
+ | **Lend** | Supply, borrow, repay, withdraw, close on Vesu V2 |
444
+ | **DCA** | Dollar-Cost Averaging with recurring buy orders (AVNU, Ekubo) |
445
+ | **Confidential** | Privacy-preserving transfers via Tongo Cash (ZK proofs) |
446
+ | **Portfolio** | Balances with USD valuations and position health |
447
+ | **Batch** | Combine swap + stake + supply + send + borrow + repay + withdraw + DCA in one transaction |
448
+ | **Gas Modes** | Gasless (pay in ERC-20) and gasfree (developer-sponsored) |
492
449
 
493
450
  ```bash
494
451
  git clone https://github.com/ahmetenesdur/starkfi-telegram-bot.git
@@ -513,6 +470,8 @@ See [`starkfi-telegram-bot/`](https://github.com/ahmetenesdur/starkfi-telegram-b
513
470
  | **Auth Server** | [Hono](https://hono.dev/) v4.12.7 + [Privy TEE](https://privy.io/) |
514
471
  | **DEX Routing** | [Fibrous](https://fibrous.finance/) (default), [AVNU](https://avnu.fi/), [Ekubo](https://ekubo.org/) |
515
472
  | **Lending** | [Vesu](https://vesu.io/) V2 Protocol |
473
+ | **DCA** | [AVNU](https://avnu.fi/), [Ekubo](https://ekubo.org/) |
474
+ | **Confidential**| [Tongo Cash](https://tongo.cash/) |
516
475
  | **Gas** | [AVNU](https://avnu.fi/) Paymaster |
517
476
 
518
477
  ---
@@ -521,15 +480,15 @@ See [`starkfi-telegram-bot/`](https://github.com/ahmetenesdur/starkfi-telegram-b
521
480
 
522
481
  StarkFi implements a robust error handling system with a custom `StarkfiError` class and **34 specific error codes** organized by domain:
523
482
 
524
- | Domain | Error Codes |
525
- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
526
- | **Auth** | `AUTH_REQUIRED`, `AUTH_FAILED`, `SESSION_EXPIRED` |
527
- | **Wallet** | `WALLET_NOT_DEPLOYED`, `WALLET_NOT_FOUND`, `INSUFFICIENT_BALANCE` |
528
- | **Network** | `NETWORK_ERROR`, `RATE_LIMITED`, `TX_FAILED`, `TX_NOT_FOUND`, `PAYMASTER_ERROR` |
529
- | **Validation** | `INVALID_CONFIG`, `INVALID_ADDRESS`, `INVALID_AMOUNT`, `INVALID_ALLOCATION` |
530
- | **DeFi** | `SWAP_FAILED`, `NO_ROUTE_FOUND`, `SLIPPAGE_EXCEEDED`, `PROVIDER_UNAVAILABLE`, `ALL_PROVIDERS_FAILED`, `STAKING_FAILED`, `LENDING_FAILED`, `DCA_FAILED`, `CONFIDENTIAL_FAILED`, `POOL_NOT_FOUND`, `EXIT_NOT_READY`, `VALIDATOR_NOT_FOUND`, `MONITOR_FAILED`, `REBALANCE_FAILED` |
531
- | **Confidential** | `CONFIDENTIAL_NOT_CONFIGURED` |
532
- | **System** | `SIMULATION_FAILED`, `BATCH_LIMIT_EXCEEDED`, `UNKNOWN` |
483
+ | Domain | Error Codes |
484
+ | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
485
+ | **Auth** | `AUTH_REQUIRED`, `AUTH_FAILED`, `SESSION_EXPIRED` |
486
+ | **Wallet** | `WALLET_NOT_DEPLOYED`, `WALLET_NOT_FOUND`, `INSUFFICIENT_BALANCE` |
487
+ | **Network** | `NETWORK_ERROR`, `RATE_LIMITED`, `TX_FAILED`, `TX_NOT_FOUND`, `PAYMASTER_ERROR` |
488
+ | **Validation** | `INVALID_CONFIG`, `INVALID_ADDRESS`, `INVALID_AMOUNT`, `INVALID_ALLOCATION` |
489
+ | **DeFi** | `SWAP_FAILED`, `NO_ROUTE_FOUND`, `SLIPPAGE_EXCEEDED`, `PROVIDER_UNAVAILABLE`, `ALL_PROVIDERS_FAILED`, `STAKING_FAILED`, `LENDING_FAILED`, `DCA_FAILED`, `CONFIDENTIAL_FAILED`, `POOL_NOT_FOUND`, `EXIT_NOT_READY`, `VALIDATOR_NOT_FOUND`, `MONITOR_FAILED`, `REBALANCE_FAILED` |
490
+ | **Confidential** | `CONFIDENTIAL_NOT_CONFIGURED` |
491
+ | **System** | `SIMULATION_FAILED`, `BATCH_LIMIT_EXCEEDED`, `UNKNOWN` |
533
492
 
534
493
  All network operations include **automatic retry with exponential backoff** (500ms base, max 2 retries). Parallel operations use a **sliding-window concurrency pool** to prevent RPC rate-limiting.
535
494