starkfi 0.3.2 → 0.4.0

package/MCP.md

@@ -278,7 +278,7 @@ Views and modifies global CLI behavior: RPC routing, network selection, and Gas
 
 | Parameter | Type   | Required | Description                                                                                                                               |
 | --------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
-| `action`  | enum   | **Yes**  | One of: `list`, `set-rpc`, `get-rpc`, `set-network`, `set-gasfree`, `set-gas-token`                                                       |
+| `action`  | enum   | **Yes**  | One of: `list`, `reset`, `set-rpc`, `get-rpc`, `set-network`, `set-gasfree`, `set-gas-token`                                                 |
 | `value`   | string | No       | `set-gasfree`: `on`/`off`. `set-gas-token`: symbol (`USDC`, `ETH`) or `reset`. `set-rpc`: URL string. `set-network`: `mainnet`/`sepolia`. |
 
 ---

package/README.md

@@ -7,11 +7,15 @@
 <h1 align="center">StarkFi</h1>
 
 <p align="center">
-  <strong>The Gas-Abstracted DeFi CLI & Agent.</strong><br>
-  <em>The AI-native DeFi toolkit for Starknet.</em><br>
+  <strong>The AI-native DeFi toolkit for Starknet.</strong><br>
   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>.
 </p>
 
+<p align="center">
+  <a href="https://www.npmjs.com/package/starkfi"><img src="https://img.shields.io/npm/v/starkfi?style=flat-square&color=CB3837&logo=npm&logoColor=white" alt="npm version"/></a>
+  <a href="https://www.npmjs.com/package/starkfi"><img src="https://img.shields.io/npm/dm/starkfi?style=flat-square&color=blue" alt="npm downloads"/></a>
+</p>
+
 ```bash
 npx starkfi@latest --help
 ```
@@ -129,13 +133,14 @@ npx starkfi@latest lend-supply 100 -p Prime -t STRK
 npx starkfi@latest lend-borrow -p Prime \
   --collateral-amount 200 --collateral-token STRK \
   --borrow-amount 50 --borrow-token USDC
-npx starkfi@latest lend-status -p Prime --collateral-token STRK --borrow-token USDC
+npx starkfi@latest lend-status                                                # Auto-scan all pools
+npx starkfi@latest lend-status -p Prime --collateral-token STRK --borrow-token USDC  # Specific position
 npx starkfi@latest lend-close -p Prime --collateral-token STRK --borrow-token USDC
 ```
 
 ### 💸 Gas Abstraction
 
-All transactions are gasless by default. Users pay gas fees in their preferred ERC-20 token via Paymaster.
+Users pay gas fees in their preferred ERC-20 token via AVNU Paymaster — no native STRK or ETH required. Alternatively, developers can sponsor gas entirely.
 
 ```bash
 # Pay gas in USDC instead of STRK
@@ -156,7 +161,7 @@ Estimate fees and validate any transaction before broadcasting.
 
 ```bash
 npx starkfi@latest trade 100 USDC ETH --simulate
-# → mode: SIMULATION, estimatedFee: 0.000142 ETH ($0.52), callCount: 4
+# → mode: SIMULATION, estimatedFee: 0.054 STRK ($0.0024), callCount: 4
 ```
 
 ### 📊 Portfolio Dashboard
@@ -323,7 +328,7 @@ npx starkfi@latest trade 10 STRK ETH               # Execute
 | `lend-withdraw <amount> -p <pool> -t <token>`                                                                                  | Withdraw assets           |
 | `lend-borrow -p <pool> --collateral-amount <n> --collateral-token <t> --borrow-amount <n> --borrow-token <t> [--use-supplied]` | Borrow                    |
 | `lend-repay <amount> -p <pool> -t <token> --collateral-token <t>`                                                              | Repay debt                |
-| `lend-status -p <pool> --collateral-token <t> [--borrow-token <t>]`                                                            | Position status           |
+| `lend-status [-p <pool> --collateral-token <t> [--borrow-token <t>]]`                                                          | Position status (auto-scan if no args) |
 | `lend-close -p <pool> --collateral-token <t> --borrow-token <t>`                                                               | Close position atomically |
 
 ### Configuration
@@ -331,6 +336,7 @@ npx starkfi@latest trade 10 STRK ETH               # Execute
 | Command                                 | Description                    |
 | --------------------------------------- | ------------------------------ |
 | `config list`                           | Show current configuration     |
+| `config reset`                          | Reset all settings to defaults |
 | `config set-rpc <url>`                  | Set custom RPC endpoint        |
 | `config get-rpc`                        | Show current RPC               |
 | `config set-network <mainnet\|sepolia>` | Switch network                 |
@@ -395,6 +401,21 @@ StarkFi implements a robust error handling system with a custom `StarkfiError` c
 
 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.
 
+### Readable Starknet Errors
+
+Raw Starknet JSON-RPC errors (hex-encoded Cairo strings like `u256_sub Overflow`) are automatically parsed into human-readable messages:
+
+| Raw Error | Displayed Message |
+|-----------|------------------|
+| `u256_sub Overflow` | Insufficient balance — you don't have enough tokens (including gas fees) |
+| `ERC20: insufficient allowance` | Token approval required — not enough allowance for this operation |
+| `UNAUTHORIZED` | Unauthorized — session may have expired, try: starkfi auth login |
+| `argent/multicall-failed` | One or more calls in the transaction failed |
+| `dusty-collateral-balance` | Collateral amount is below the pool's minimum (dust limit). Please increase the amount. |
+| `dusty-debt-balance` | Borrow amount is below the pool's minimum (dust limit). Please increase the amount. |
+
+This applies to both CLI output (`formatError`) and MCP responses (`withErrorHandling`).
+
 ---
 
 ## Development