Architecture Overview

src/
├── index.ts          # CLI entry point (Commander.js)
├── commands/         # 14 command directories
│   ├── auth/         # login, verify, logout
│   ├── wallet/       # address, balance, send, deploy
│   ├── trade/        # trade, multi-swap
│   ├── staking/      # stake, unstake, rewards, pools, validators, stake-status
│   ├── lending/      # lend-pools, lend-supply, lend-withdraw, lend-borrow, lend-repay, lend-close, lend-status, lend-monitor, lend-auto
│   ├── dca/          # dca-preview, dca-create, dca-list, dca-cancel
│   ├── troves/       # troves-list, troves-position, troves-deposit, troves-withdraw
│   ├── lst/          # lst-position, lst-stats, lst-stake, lst-redeem, lst-exit-all
│   ├── confidential/ # conf-setup, conf-balance, conf-fund, conf-transfer, conf-withdraw, conf-ragequit, conf-rollover
│   ├── batch/        # batch multicall
│   ├── portfolio/    # portfolio dashboard
│   ├── config/       # config subcommands
│   ├── chain/        # tx-status
│   └── system/       # status (mcp-start is inline in index.ts)
├── services/         # 17 service modules
│   ├── starkzap/     # SDK client initialization + config
│   ├── fibrous/      # DEX routing, calldata, pricing
│   ├── vesu/         # Lending pool API + on-chain operations
│   ├── staking/      # Validator resolution + pool operations
│   ├── dca/          # DCA order management (create, cancel, list, preview)
│   ├── troves/       # Troves vault strategy operations
│   ├── lst/          # Endur liquid staking operations
│   ├── confidential/ # Tongo Cash config + privacy-preserving transfers
│   ├── tokens/       # Token resolution + balance queries
│   ├── batch/        # Multicall composition via TxBuilder
│   ├── simulate/     # Transaction simulation (fee estimation)
│   ├── portfolio/    # Aggregated DeFi overview
│   ├── auth/         # Session management (JWT persistence)
│   ├── api/          # Backend API client
│   ├── config/       # Configuration persistence
│   ├── price/        # USD pricing via Fibrous
│   └── swap/         # Multi-provider swap aggregation (Fibrous, AVNU, Ekubo)
├── mcp/              # MCP server layer
│   ├── server.ts     # Server setup + stdio transport
│   ├── tools/        # 9 domain tool files + 2 utilities (Zod schemas)
│   └── handlers/     # 13 domain handlers + 3 utility files
└── lib/              # 16 shared utilities
    ├── errors.ts     # ErrorCode enum (36 codes) + StarkfiError class
    ├── parse-starknet-error.ts # Cairo hex decoding + error map (15 patterns)
    ├── retry.ts      # Exponential backoff retry
    ├── concurrency.ts # Sliding-window concurrent execution
    ├── fetch.ts      # Fetch with AbortController timeout
    ├── format.ts     # Table, result, and error formatting
    ├── cli-helpers.ts # runCommand wrapper + outputResult
    ├── command-runner.ts # withAuthenticatedWallet centralized runner
    ├── validation.ts # Address and input validation
    ├── types.ts      # Shared TypeScript types
    ├── config.ts     # Config file paths (XDG-compliant)
    ├── brand.ts      # CLI branding and colors
    ├── command.ts    # Commander.js helpers
    ├── send-with-preflight.ts # Mandatory simulation before tx execution
    ├── tx-progress.ts # Real-time transaction progress tracking
    └── resolve-network.ts # Network resolution priority chain

Tool Registration (mcp/tools/)     → Zod schema + description
       ↓
Handler          (mcp/handlers/)   → Input validation + orchestration
       ↓
Service          (services/)       → Business logic + SDK calls

// Example: Query 50 token balances with max 10 concurrent RPC calls
const balances = await runConcurrent(tokens, 10, async (token) => {
	const balance = await wallet.balanceOf(token);
	return balance.isZero() ? undefined : { token, balance };
});