@solana-compass/cli 0.1.0 → 0.2.1

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

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

@@ -0,0 +1,150 @@
+# Wallet Commands Reference
+
+## Create a Wallet
+
+```bash
+sol wallet create                         # auto-named (wallet-1, wallet-2, ...)
+sol wallet create --name trading          # pick a name
+sol wallet create --name bot --count 5    # batch-create 5 wallets
+```
+
+Creates a new Ed25519 keypair and stores it as a JSON key file in
+`~/.sol/wallets/<name>.json` (Solana CLI compatible format, chmod 600).
+
+The first wallet created becomes the default for all commands.
+
+## List Wallets
+
+```bash
+sol wallet list                           # all wallets with SOL balances
+sol wallet list --label trading           # filter by label
+```
+
+Shows wallet name, address, SOL balance, and whether it's the default.
+Hints at `sol wallet balance <name>` for full token breakdown.
+
+## Check Balances
+
+```bash
+sol wallet balance                        # default wallet, all tokens + USD
+sol wallet balance trading                # specific wallet
+```
+
+Displays every token held with current USD values. Tokens below the
+dust threshold ($0.0001) are grouped as dust.
+
+## Import an Existing Wallet
+
+```bash
+sol wallet import --solana-cli            # from ~/.config/solana/id.json
+sol wallet import ./keypair.json --name cold
+sol wallet import /path/to/key.json
+```
+
+Copies the key file into `~/.sol/wallets/`. The `--solana-cli` flag
+imports from the default Solana CLI keypair location.
+
+## Export / Show Key File Path
+
+```bash
+sol wallet export main
+```
+
+Prints the file system path to the key file. Does NOT print the
+private key itself.
+
+## Remove a Wallet
+
+```bash
+sol wallet remove old-wallet
+```
+
+Removes the wallet from the registry. The key file is renamed with a
+`.deleted` suffix (not permanently deleted) so it can be recovered.
+
+## Set Default Wallet
+
+```bash
+sol wallet set-default trading
+```
+
+Changes which wallet is used when `--wallet` is not specified.
+
+## Labels
+
+```bash
+sol wallet label main --add trading       # add a label
+sol wallet label main --add defi --add bot  # multiple labels
+sol wallet label main --remove trading    # remove a label
+```
+
+Labels are freeform tags for organizing wallets. Use them with
+`sol wallet list --label <label>` to filter.
+
+## Transaction History
+
+```bash
+sol wallet history                        # recent transactions
+sol wallet history --limit 20            # more results
+sol wallet history --type swap           # filter by type (swap, send, stake, lend)
+sol wallet history trading               # specific wallet
+```
+
+Shows transactions from the local log — type, tokens, amounts, USD
+values at execution time, and timestamps.
+
+## Fund via Fiat Onramp
+
+```bash
+sol wallet fund                          # default wallet, default amount
+sol wallet fund --amount 50              # specify USD amount
+sol wallet fund trading --provider moonpay
+```
+
+Generates a URL to purchase SOL via a fiat onramp provider. Opens
+in your browser.
+
+## Global Wallet Flag
+
+Any command that operates on a wallet accepts `--wallet <name-or-address>`:
+
+```bash
+sol token swap 50 usdc bonk --wallet trading
+sol stake new 10 --wallet cold
+sol lend deposit 100 usdc --wallet defi
+```
+
+## JSON Output
+
+All wallet commands support `--json`:
+
+```bash
+sol wallet list --json
+sol wallet balance --json
+```
+
+### Example: `sol wallet list --json`
+
+```json
+{
+  "ok": true,
+  "data": {
+    "wallets": [
+      {
+        "name": "main",
+        "address": "7nY...xyz",
+        "sol_balance": 12.5,
+        "is_default": true,
+        "labels": ["trading"]
+      }
+    ]
+  },
+  "meta": { "elapsed_ms": 320 }
+}
+```
+
+## Data Storage
+
+- Key files: `~/.sol/wallets/<name>.json`
+- Wallet registry: `~/.sol/data.db` (SQLite)
+- Config: `~/.sol/config.toml`