@byreal-io/byreal-cli-realclaw 0.4.4 → 0.4.5

package/dist/index.cjs

@@ -3573,7 +3573,7 @@ var INJECTED_VERSION, VERSION, CLI_NAME, NPM_PACKAGE, API_BASE_URL, API_ENDPOINT
 var init_constants = __esm({
   "src/core/constants.ts"() {
     "use strict";
-    INJECTED_VERSION = true ? "0.4.4" : void 0;
+    INJECTED_VERSION = true ? "0.4.5" : void 0;
     VERSION = INJECTED_VERSION ?? process.env.npm_package_version ?? "0.0.0";
     CLI_NAME = "byreal-cli";
     NPM_PACKAGE = "@byreal-io/byreal-cli-realclaw";
@@ -92113,6 +92113,19 @@ The multi-step flow is the default for backward compatibility; if Privy is confi
 ### Balance Check on Dry-run
 \`positions open --dry-run\` and \`positions increase --dry-run\` automatically check wallet balance. If insufficient, response includes \`balanceWarnings\` (deficit) and \`walletBalances\` (all available tokens) \u2014 no need to run \`wallet balance\` separately.
 
+**Important caveat:** the dry-run balance check does NOT subtract the SOL fee/rent buffer (see "SOL Buffer for CLMM Position Ops" below). When SOL is one of the deposit tokens, dry-run reporting "sufficient" is necessary-but-not-sufficient \u2014 always size the SOL leg against \`sol_balance \u2212 buffer\`, not the full balance.
+
+### SOL Buffer for CLMM Position Ops
+Opening or increasing a CLMM position consumes SOL **on top of** the SOL you deposit, to pay for account rent + tx + priority fee. The dry-run balance check does not deduct this for you \u2014 you must size the deposit yourself.
+
+| Operation                  | Reserve at least | What the buffer pays for                                            |
+| -------------------------- | ---------------- | ------------------------------------------------------------------- |
+| \`positions open\`         | **0.03 SOL**     | Position NFT mint + position account rent + tick-array init + fees  |
+| \`positions increase\`     | **0.01 SOL**     | Tx + priority fee only (no new accounts)                            |
+| \`swap execute\`           | **0.01 SOL**     | Tx + priority fee (+ ATA creation if first time for output mint)    |
+
+When SOL is one of the deposit tokens, compute \`usable_sol = sol_balance \u2212 buffer\` and size the SOL leg against \`usable_sol\`. For \`--amount-usd\`, cap so the SOL leg's USD value \u2264 \`usable_sol \xD7 sol_price\`. **Never put 100% of SOL into a position.**
+
 ### Config Keys
 Supported keys for \`config get/set\`: rpc_url, cluster, defaults.slippage_bps, defaults.priority_fee_micro_lamports, privy_proxy_url, privy_api_base_path
 
@@ -92128,11 +92141,12 @@ When the user asks about investment opportunities, potential pools, or yield far
 
 1. **Analyze pool**: \`byreal-cli pools analyze <pool-id> -o json\`
 2. **Choose range** from rangeAnalysis (Conservative \xB130%, Balanced \xB115%, Aggressive \xB15%)
-3. **Preview**:
+3. **Reserve SOL buffer FIRST**: read SOL balance, compute \`usable_sol = sol_balance \u2212 0.03\`. If the pool's token pair includes SOL, size the SOL leg against \`usable_sol\`, never against the full balance. For \`--amount-usd\`, cap so the SOL leg \u2264 \`usable_sol \xD7 sol_price\`. (See "SOL Buffer for CLMM Position Ops".)
+4. **Preview**:
    - USD budget: \`positions open --pool <id> --price-lower <p> --price-upper <p> --amount-usd <usd> --dry-run -o json\`
    - Token amount: \`positions open --pool <id> --price-lower <p> --price-upper <p> --base MintA --amount <amt> --dry-run -o json\`
-4. **If insufficient balance**: dry-run response includes \`balanceWarnings\` (deficit) + \`walletBalances\` (all tokens). Pick a swap source from ANY token in the wallet (prefer highest USD balance, stablecoins/SOL for lower slippage), swap to cover the deficit. **Wait 3-5 seconds** after swap before re-running dry-run (RPC propagation delay).
-5. **Run for real**: drop \`--dry-run\` (keep \`--wallet-address <addr>\`). The default emits an unsigned base64 transaction \`{ unsignedTransactions: [...] }\` for an external signer (back-compat). Add \`--execute\` to sign + broadcast via Privy directly \u2192 \`{ signature, explorer }\`.
+5. **If insufficient balance**: dry-run response includes \`balanceWarnings\` (deficit) + \`walletBalances\` (all tokens). Pick a swap source from ANY token in the wallet (prefer highest USD balance, stablecoins/SOL for lower slippage), swap to cover the deficit. **Wait 3-5 seconds** after swap before re-running dry-run (RPC propagation delay). **Do not swap repeatedly \u2014 recompute the position math first** (see "Position Math Sanity Check" in Troubleshooting).
+6. **Run for real**: drop \`--dry-run\` (keep \`--wallet-address <addr>\`). The default emits an unsigned base64 transaction \`{ unsignedTransactions: [...] }\` for an external signer (back-compat). Add \`--execute\` to sign + broadcast via Privy directly \u2192 \`{ signature, explorer }\`.
 
 ## Workflow: Increase/Decrease Liquidity
 
@@ -92140,9 +92154,10 @@ When user wants to add more liquidity to an existing position or partially withd
 
 **Increase liquidity**:
 1. \`byreal-cli positions list -o json\` \u2014 find the position's NFT mint address
-2. \`byreal-cli positions increase --nft-mint <nft-mint> --amount-usd <usd> --dry-run -o json\` \u2014 preview (includes balance check)
-3. If insufficient balance \u2192 swap to get required tokens (see "Insufficient Balance" workflow)
-4. \`byreal-cli positions increase --nft-mint <nft-mint> --amount-usd <usd> --wallet-address <addr> -o json\` \u2014 emit unsigned tx (default). Add \`--execute\` to sign + broadcast via Privy.
+2. Reserve **0.01 SOL** buffer; if the pool includes SOL, size the SOL leg against \`sol_balance \u2212 0.01\`.
+3. \`byreal-cli positions increase --nft-mint <nft-mint> --amount-usd <usd> --dry-run -o json\` \u2014 preview (includes balance check; remember it does NOT deduct the SOL buffer)
+4. If insufficient balance \u2192 swap to get required tokens (see "Insufficient Balance" workflow). Re-run dry-run after the swap settles \u2014 don't assume the prior deficit number still applies.
+5. \`byreal-cli positions increase --nft-mint <nft-mint> --amount-usd <usd> --wallet-address <addr> -o json\` \u2014 emit unsigned tx (default). Add \`--execute\` to sign + broadcast via Privy.
 
 **Decrease liquidity** (partial withdrawal):
 1. \`byreal-cli positions list -o json\` \u2014 find the position's NFT mint address
@@ -92265,12 +92280,17 @@ Always read \`error.message\` carefully \u2014 it contains the specific cause. D
 4. **Increase slippage**: \`--slippage 300\` for volatile tokens
 
 ### Positions
-1. **Insufficient balance**: \`--dry-run\` reports \`balanceWarnings\` with exact deficit. Use the swap workflow to cover it, wait 3-5s, then retry.
-2. **Slippage exceeded**: Price moved during execution. Increase \`--slippage\` (e.g., 200-300 bps) or re-run \`--dry-run\` to get updated prices.
-3. **Position already closed**: Check \`positions list --status 0\` \u2014 the NFT is burned after close.
-4. **No fees to claim**: Position may be out-of-range (not earning fees) or fees already claimed.
-5. **Wrong NFT mint**: Ensure you use the NFT mint address from \`positions list\`, not the pool address or position PDA.
-6. **Stale state after tx**: After any on-chain operation, wait 3-5 seconds before the next query \u2014 RPC propagation delay.
+1. **Insufficient balance** (dry-run): \`deficit\` is the **slippage-padded upper bound** (non-base leg uses \`otherAmountMax = otherAmount \xD7 (1 + slippage)\`), not the exact amount that will be consumed. Before swapping, **first try a tighter \`--slippage\` and re-run dry-run** \u2014 the warning often disappears. If you still must swap, do not over-swap the full \`deficit\`; re-run dry-run after the swap settles.
+2. **Insufficient funds at \`--execute\` despite dry-run "sufficient"**: this is **almost always a missing SOL buffer**, not a stale RPC / cache / indexer issue. The dry-run check does NOT deduct the ~0.03 SOL needed for new-position rent + fees (see "SOL Buffer for CLMM Position Ops"). Resize the SOL leg against \`sol_balance \u2212 0.03\` and retry. **Do not** start swapping to "balance" the wallet before doing this math \u2014 that path burned real money in past incidents.
+3. **Position Math Sanity Check** (before any swap to "cover a deficit"): for a CLMM position at current price \`p\`, lower \`pL\`, upper \`pU\`, the deposit split is **not 50/50**. Required amounts: \`USDC \u221D \u221Ap \u2212 \u221ApL\`, \`SOL \u221D (\u221ApU \u2212 \u221Ap) / (\u221Ap \xB7 \u221ApU)\`. Always recompute from a fresh \`--dry-run\` after any swap; do not assume the previous deficit number still applies. Ping-ponging swaps without re-running dry-run is the failure mode that wastes gas.
+4. **Slippage exceeded**: Price moved during execution. Increase \`--slippage\` (e.g., 200-300 bps) or re-run \`--dry-run\` to get updated prices.
+5. **Position already closed**: Check \`positions list --status 0\` \u2014 the NFT is burned after close.
+6. **No fees to claim**: Position may be out-of-range (not earning fees) or fees already claimed.
+7. **Wrong NFT mint**: Ensure you use the NFT mint address from \`positions list\`, not the pool address or position PDA.
+8. **Stale state after tx**: After any on-chain operation, wait 3-5 seconds before the next query \u2014 RPC propagation delay (seconds, not minutes).
+
+### What \`--execute\` actually does (don't misdiagnose)
+\`--execute\` flow: CLI builds unsigned tx \u2192 Privy proxy \u2192 \`signAndBroadcast\` \u2192 Solana RPC \`simulateTransaction\` against **live chain state**. There is **no Privy indexer and no cached balance** in this path. If you see "insufficient funds" from \`--execute\`, treat it as a real on-chain shortfall (almost always the SOL buffer \u2014 see Positions #2), not as stale data. RPC nodes can lag by **seconds** after a fresh swap, not minutes \u2014 if a retry is needed, one 3-5s wait is enough. If three retries still fail, **stop** and re-run the math; do not keep retrying.
 
 `;
 function createSkillCommand() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byreal-io/byreal-cli-realclaw",
-  "version": "0.4.4",
+  "version": "0.4.5",
   "description": "AI-native CLI for Byreal CLMM DEX on Solana",
   "type": "module",
   "main": "dist/index.cjs",