@solana-compass/cli 0.2.0 → 0.2.1

package/skills/solana-payments-wallets-trading/references/portfolio-commands.md

@@ -0,0 +1,128 @@
+# Portfolio Commands Reference
+
+## View Portfolio
+
+```bash
+sol portfolio
+sol portfolio --wallet trading
+```
+
+Unified view of everything you hold — tokens, staked SOL, and lending
+positions — with USD values.
+
+### JSON Output
+
+```json
+{
+  "ok": true,
+  "data": {
+    "positions": [
+      {
+        "type": "token",
+        "symbol": "SOL",
+        "amount": 12.5,
+        "value_usd": 1878.13
+      },
+      {
+        "type": "stake",
+        "symbol": "SOL",
+        "amount": 10,
+        "value_usd": 1502.50,
+        "validator": "Comp...ass",
+        "status": "active"
+      },
+      {
+        "type": "lend",
+        "symbol": "USDC",
+        "amount": 100,
+        "value_usd": 100,
+        "protocol": "kamino",
+        "apy": "8.5%"
+      }
+    ],
+    "total_value_usd": 3480.63
+  },
+  "meta": { "elapsed_ms": 2500 }
+}
+```
+
+## Take a Snapshot
+
+```bash
+sol portfolio snapshot
+sol portfolio snapshot --label "pre-trade"
+sol portfolio snapshot --wallet trading
+```
+
+Saves the current portfolio state to SQLite for later comparison.
+
+### Flags
+
+| Flag | Description |
+|------|-------------|
+| `--label <text>` | Human-readable label for the snapshot |
+| `--wallet <name>` | Snapshot a specific wallet only |
+
+Snapshots include ALL position types — tokens, stakes, and lending.
+
+## List Snapshot History
+
+```bash
+sol portfolio history
+```
+
+Lists all saved snapshots with ID, timestamp, label, and total value.
+
+## Compare to a Snapshot
+
+```bash
+sol portfolio compare                     # vs latest snapshot
+sol portfolio compare 3                   # vs snapshot #3
+sol portfolio compare --wallet trading
+```
+
+Shows what changed since the snapshot — added/removed positions,
+value changes, token price movements.
+
+## Profit and Loss
+
+```bash
+sol portfolio pnl
+sol portfolio pnl --since 5              # P&L since snapshot #5
+sol portfolio pnl --wallet trading
+```
+
+Calculates profit and loss based on the transaction log and snapshots.
+The transaction log records USD prices at execution time, so cost
+basis is computed automatically.
+
+### Flags
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--since <id>` | first snapshot | Calculate P&L from this snapshot |
+| `--wallet <name>` | all wallets | Limit to a specific wallet |
+
+## Delete a Snapshot
+
+```bash
+sol portfolio delete 3
+```
+
+Permanently removes a snapshot by ID.
+
+## Automated Snapshots
+
+```bash
+sol portfolio cron
+```
+
+Prints a crontab entry you can install to take snapshots automatically
+(e.g. daily at midnight). Useful for long-running portfolio tracking.
+
+## Tips
+
+- Take snapshots before and after significant trades to measure impact
+- Use labels to mark meaningful points ("post-rebalance", "pre-airdrop")
+- The transaction log is the source of truth for cost basis — snapshots
+  are for point-in-time comparisons

package/skills/solana-payments-wallets-trading/references/staking-commands.md

@@ -0,0 +1,150 @@
+# Staking Commands Reference
+
+## Create a New Stake
+
+```bash
+sol stake new <amount>
+```
+
+Creates a stake account, funds it with `<amount>` SOL, and delegates
+to a validator — all in a single transaction.
+
+### Examples
+
+```bash
+sol stake new 10                          # stake 10 SOL (default validator)
+sol stake new 5 --validator DPm...xyz     # specific validator
+sol stake new 10 --wallet cold            # from a specific wallet
+```
+
+### Flags
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--validator <vote-address>` | Solana Compass | Validator to delegate to |
+| `--wallet <name>` | default | Wallet to fund the stake from |
+
+### JSON Output
+
+```json
+{
+  "ok": true,
+  "data": {
+    "signature": "3xY...abc",
+    "stake_account": "7gK...def",
+    "amount_sol": 10,
+    "validator": "Comp...ass"
+  },
+  "meta": { "elapsed_ms": 2500 }
+}
+```
+
+## List Stake Accounts
+
+```bash
+sol stake list
+sol stake list --wallet cold
+```
+
+Shows all stake accounts for the wallet — address, amount staked,
+validator, status (activating/active/deactivating/inactive), and
+any claimable MEV tips.
+
+Hints at `sol stake claim-mev` when tips are available.
+
+### JSON Output
+
+```json
+{
+  "ok": true,
+  "data": {
+    "stakes": [
+      {
+        "address": "7gK...def",
+        "amount_sol": 10,
+        "validator": "Comp...ass",
+        "status": "active",
+        "claimable_mev_sol": 0.05
+      }
+    ],
+    "total_staked_sol": 10,
+    "total_claimable_mev_sol": 0.05
+  },
+  "meta": { "elapsed_ms": 1200 }
+}
+```
+
+## Claim MEV Tips
+
+```bash
+sol stake claim-mev
+sol stake claim-mev --withdraw
+sol stake claim-mev 7gK...def
+```
+
+Claims MEV tips earned by your stake accounts.
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--withdraw` | false | Send tips to wallet instead of re-staking (compounding) |
+| `--wallet <name>` | default | Wallet that owns the stake accounts |
+
+By default, tips are compounded (re-staked). Use `--withdraw` to
+withdraw them to your wallet instead.
+
+You can specify a single stake account address to claim from, or
+omit it to claim from all accounts.
+
+## Withdraw / Unstake
+
+```bash
+sol stake withdraw <stake-account> [amount]
+```
+
+Withdraws SOL from a stake account. Handles the deactivation process
+automatically:
+
+- **Active stake**: Deactivates first, then you can withdraw after the
+  cooldown epoch
+- **Inactive stake**: Withdraws immediately
+- **Partially withdraw**: Specify an amount to split and withdraw
+
+### Examples
+
+```bash
+sol stake withdraw 7gK...abc              # withdraw all from this account
+sol stake withdraw 7gK...abc 5            # withdraw 5 SOL (splits if needed)
+sol stake withdraw 7gK...abc --force      # force deactivate active stake
+```
+
+### Flags
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--wallet <name>` | default | Authority wallet |
+| `--force` | false | Force deactivation of active stake |
+
+### JSON Output
+
+```json
+{
+  "ok": true,
+  "data": {
+    "signature": "2bC...xyz",
+    "stake_account": "7gK...abc",
+    "withdrawn_sol": 10,
+    "action": "withdrawn"
+  },
+  "meta": { "elapsed_ms": 1800 }
+}
+```
+
+## Validator Selection
+
+The default validator is Solana Compass. Override with `--validator`:
+
+```bash
+sol stake new 10 --validator DPmsofDi1YBSvDJzeUSGMiHjEGkzKFKMZRiM7GYsTKcf
+```
+
+Use a vote account address (not the node identity).

package/skills/solana-payments-wallets-trading/references/trading-commands.md

@@ -0,0 +1,207 @@
+# Trading Commands Reference
+
+## Swap Tokens
+
+```bash
+sol token swap <amount> <from> <to>
+```
+
+Swaps tokens via Jupiter aggregator — best price across all Solana DEXes.
+
+### Examples
+
+```bash
+sol token swap 50 usdc bonk               # buy BONK with USDC
+sol token swap 1.5 sol usdc               # sell SOL for USDC
+sol token swap 100 usdc sol --wallet bot   # from a specific wallet
+sol token swap 50 usdc bonk --quote-only   # preview without executing
+sol token swap 50 usdc bonk --slippage 100 # 1% slippage (100 bps)
+sol token swap 50 usdc bonk --yes          # skip confirmation
+```
+
+### Flags
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--slippage <bps>` | 50 | Slippage tolerance in basis points (50 = 0.5%) |
+| `--quote-only` | false | Show quote without executing |
+| `--wallet <name>` | default | Wallet to swap from |
+| `--yes` | false | Skip confirmation prompt |
+
+### Token Resolution
+
+Tokens can be specified by symbol (`sol`, `usdc`, `bonk`) or mint
+address. Resolution order:
+
+1. Hardcoded well-known list (SOL, USDC, USDT, JUP, BONK, mSOL,
+   jitoSOL, bSOL, ETH, wBTC, PYTH, JTO, WEN, RNDR, JLP)
+2. Local SQLite cache (24-hour TTL)
+3. Jupiter Token API (ranked by liquidity)
+
+For safety with unfamiliar tokens, verify with `sol token info <symbol>`
+first, or use the mint address directly.
+
+### JSON Output
+
+```json
+{
+  "ok": true,
+  "data": {
+    "signature": "4xK9...abc",
+    "from_token": "USDC",
+    "from_amount": 50,
+    "to_token": "BONK",
+    "to_amount": 2500000,
+    "price_impact": "0.01%",
+    "from_price_usd": 1.0,
+    "to_price_usd": 0.00002
+  },
+  "meta": { "elapsed_ms": 2100 }
+}
+```
+
+## Send Tokens
+
+```bash
+sol token send <amount> <token> <recipient>
+```
+
+Send SOL or any SPL token to a wallet address.
+
+### Examples
+
+```bash
+sol token send 2 sol 7nY...xyz
+sol token send 50 usdc GkX...abc
+sol token send 1000 bonk AgE...def --yes
+sol token send 0.5 sol 7nY...xyz --wallet trading
+```
+
+### Flags
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--wallet <name>` | default | Wallet to send from |
+| `--yes` | false | Skip confirmation prompt |
+
+In `--json` mode, confirmations are always skipped.
+
+### JSON Output
+
+```json
+{
+  "ok": true,
+  "data": {
+    "signature": "5aB...xyz",
+    "token": "USDC",
+    "amount": 50,
+    "recipient": "GkX...abc",
+    "price_usd": 1.0
+  },
+  "meta": { "elapsed_ms": 1500 }
+}
+```
+
+## Check Prices
+
+```bash
+sol token price <symbols...>
+```
+
+### Examples
+
+```bash
+sol token price sol                       # single token
+sol token price sol usdc bonk eth         # multiple at once
+```
+
+Prices come from Jupiter Price API with CoinGecko fallback.
+
+### JSON Output
+
+```json
+{
+  "ok": true,
+  "data": {
+    "prices": [
+      { "symbol": "SOL", "price_usd": 150.25, "mint": "So11...1112" }
+    ]
+  },
+  "meta": { "elapsed_ms": 200 }
+}
+```
+
+## Token Info
+
+```bash
+sol token info <symbol>
+```
+
+Shows token metadata — mint address, decimals, total supply. Useful
+for verifying which token a symbol resolves to before transacting.
+
+## List Tokens
+
+```bash
+sol token list                            # default wallet
+sol token list --wallet trading           # specific wallet
+```
+
+Lists all tokens held in the wallet with balances and USD values.
+
+## Burn Tokens
+
+```bash
+sol token burn <symbol> [amount]
+```
+
+### Examples
+
+```bash
+sol token burn bonk 1000                  # burn specific amount
+sol token burn bonk --all                 # burn entire balance
+sol token burn bonk --all --close         # burn and close the account
+```
+
+### Flags
+
+| Flag | Description |
+|------|-------------|
+| `--all` | Burn entire balance |
+| `--close` | Close the token account after burning (reclaims ~0.002 SOL rent) |
+| `--wallet <name>` | Wallet to burn from |
+| `--yes` | Skip confirmation |
+
+## Close Token Accounts
+
+```bash
+sol token close [symbol]
+```
+
+Closes empty token accounts and reclaims rent (~0.002 SOL each).
+
+### Examples
+
+```bash
+sol token close usdc                      # close specific account
+sol token close --all --yes               # close all empty accounts
+sol token close --all --burn --yes        # burn dust + close all
+```
+
+### Flags
+
+| Flag | Description |
+|------|-------------|
+| `--all` | Close all eligible accounts |
+| `--burn` | Burn remaining dust before closing |
+| `--wallet <name>` | Wallet to close accounts in |
+| `--yes` | Skip confirmation |
+
+## Sync Token Cache
+
+```bash
+sol token sync
+```
+
+Refreshes the local token metadata cache from Jupiter's token list.
+Normally not needed — tokens are cached on first use.

package/skills/solana-payments-wallets-trading/references/troubleshooting.md

@@ -0,0 +1,158 @@
+# Troubleshooting
+
+## RPC Issues
+
+### "Rate limited" or slow responses
+
+The public Solana RPC (`api.mainnet-beta.solana.com`) rate-limits
+aggressively. Set a dedicated RPC endpoint:
+
+```bash
+sol config set rpc.url https://your-rpc-endpoint.com
+```
+
+Free RPC tiers are available from Helius, Triton, and QuickNode.
+
+### RPC resolution order
+
+The CLI finds an RPC endpoint in this order:
+
+1. `--rpc` flag on the command
+2. `SOL_RPC_URL` environment variable
+3. `~/.sol/config.toml` → `rpc.url`
+4. Solana CLI config (`solana config get`)
+5. Public mainnet RPC (with warning)
+
+### "Failed to fetch blockhash" / connection errors
+
+- Check that your RPC URL is correct: `sol config get rpc.url`
+- Verify the endpoint is reachable: `curl <your-rpc-url> -X POST -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":1,"method":"getHealth"}'`
+- Try a different RPC provider
+
+## Token Resolution
+
+### Wrong token resolved
+
+Symbol search is ranked by liquidity, but ambiguous symbols can
+resolve to the wrong token. To verify:
+
+```bash
+sol token info <symbol>       # check the mint address
+```
+
+To avoid ambiguity, use the mint address directly:
+
+```bash
+sol token swap 50 usdc EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
+```
+
+### "Token not found"
+
+- Run `sol token sync` to refresh the local cache
+- Use the full mint address instead of a symbol
+- Check if the token exists on Jupiter: some very new or illiquid
+  tokens may not be indexed yet
+
+## Transaction Issues
+
+### "Transaction simulation failed"
+
+Common causes:
+- **Insufficient balance**: Check with `sol wallet balance`
+- **Slippage exceeded**: Increase with `--slippage <bps>` (e.g. `--slippage 200` for 2%)
+- **Account not initialized**: The CLI creates associated token accounts
+  automatically, but some edge cases may require manual setup
+
+### "Transaction expired"
+
+Solana transactions have a ~60-second lifetime. This can happen when:
+- The RPC is slow to relay the transaction
+- Network congestion is high
+
+The CLI retries automatically with backoff. If it keeps failing, try
+again or use a faster RPC endpoint.
+
+### "Blockhash not found"
+
+Usually means the transaction took too long to confirm. The CLI
+handles retry logic, but persistent failures suggest RPC issues.
+
+## Wallet Issues
+
+### "No wallets found"
+
+Create one:
+
+```bash
+sol wallet create --name main
+```
+
+Or import from Solana CLI:
+
+```bash
+sol wallet import --solana-cli
+```
+
+### "Wallet not found: <name>"
+
+Check available wallets:
+
+```bash
+sol wallet list
+```
+
+Wallet names are case-sensitive.
+
+### Recovering a removed wallet
+
+`sol wallet remove` renames the key file to `<name>.json.deleted` in
+`~/.sol/wallets/`. To recover, rename it back:
+
+```bash
+mv ~/.sol/wallets/old-wallet.json.deleted ~/.sol/wallets/old-wallet.json
+```
+
+Then re-import it:
+
+```bash
+sol wallet import ~/.sol/wallets/old-wallet.json --name old-wallet
+```
+
+## Staking Issues
+
+### "Stake account is activating"
+
+New stakes take 1 epoch (~2-3 days) to become active. During this
+time, the account shows as "activating" and cannot be withdrawn.
+
+### "Cannot withdraw active stake"
+
+Active stake must be deactivated first. Use `--force` to deactivate:
+
+```bash
+sol stake withdraw 7gK...abc --force
+```
+
+After deactivation, wait one epoch for it to become inactive, then
+withdraw.
+
+## Database Issues
+
+### Corrupted database
+
+The SQLite database is at `~/.sol/data.db`. If it becomes corrupted:
+
+```bash
+rm ~/.sol/data.db
+```
+
+The CLI will recreate it on next run. You'll lose transaction history
+and snapshots, but wallet key files are stored separately and are
+not affected.
+
+## General Tips
+
+- Use `--verbose` on any command to see debug output
+- Use `--json` to get structured error messages with error codes
+- Check `sol config list` to verify your settings
+- Run `sol network` to verify RPC connectivity and see network status