@byreal-io/byreal-cli-realclaw 0.3.2 → 0.3.3

package/README.md

@@ -66,7 +66,7 @@ All commands support `-o json` for structured output.
 | `pools analyze`           | Comprehensive pool analysis (APR, risk, range) |
 | `tokens list`             | List available tokens                          |
 | `swap execute`            | Preview or execute a token swap                |
-| `positions list`          | List your CLMM positions                       |
+| `positions list`          | List positions (own wallet or any via --user)   |
 | `positions open`          | Open a new CLMM position                       |
 | `positions increase`      | Add liquidity to an existing position           |
 | `positions decrease`      | Partially remove liquidity from a position      |
@@ -74,6 +74,7 @@ All commands support `-o json` for structured output.
 | `positions claim`           | Claim trading fees                              |
 | `positions claim-rewards`   | Claim incentive rewards from positions           |
 | `positions claim-bonus`     | Claim CopyFarmer bonus rewards                  |
+| `positions submit-rewards`  | Submit signed reward/bonus transactions to backend |
 | `positions analyze`       | Analyze an existing position                   |
 | `positions top-positions` | View top positions in a pool                   |
 | `positions copy`          | Copy a farmer's position                       |

package/dist/index.cjs

@@ -3033,7 +3033,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.3.2" : void 0;
+    INJECTED_VERSION = true ? "0.3.3" : void 0;
     VERSION = INJECTED_VERSION ?? process.env.npm_package_version ?? "0.0.0";
     CLI_NAME = "byreal-cli";
     NPM_PACKAGE = "@byreal-io/byreal-cli-realclaw";
@@ -3061,6 +3061,7 @@ var init_constants = __esm({
       // Reward / Bonus claim endpoints
       UNCLAIMED_DATA: "/byreal/api/dex/v2/position/unclaimed-data",
       REWARD_ENCODE: "/byreal/api/dex/v2/incentive/encode-v2",
+      REWARD_ORDER: "/byreal/api/dex/v2/incentive/order-v2",
       // Fee endpoints
       AUTO_FEE: "/byreal/api/dex/v2/main/auto-fee"
     };
@@ -82846,6 +82847,19 @@ async function encodeReward(params) {
   }
   return { ok: true, value: data };
 }
+async function submitRewardOrder(params) {
+  const result = await apiClient.post(API_ENDPOINTS.REWARD_ORDER, {
+    orderCode: params.orderCode,
+    walletAddress: params.walletAddress,
+    signedTxPayload: params.signedTxPayload
+  });
+  if (!result.ok) return result;
+  const data = result.value.result?.data;
+  if (!data) {
+    return { ok: true, value: { orderCode: "", txList: [], claimTokenList: [] } };
+  }
+  return { ok: true, value: data };
+}
 var api = {
   listPools,
   getPoolInfo,
@@ -82860,7 +82874,8 @@ var api = {
   getUnclaimedData,
   getEpochBonus,
   getProviderOverview,
-  encodeReward
+  encodeReward,
+  submitRewardOrder
 };
 
 // src/cli/commands/pools.ts
@@ -83555,6 +83570,25 @@ function outputError(error, format) {
     outputErrorTable(error);
   }
 }
+function outputRewardOrderResult(result) {
+  console.log(source_default.green.bold("\nRewards Claimed\n"));
+  if (result.claimTokenList.length > 0) {
+    console.log(source_default.white.bold("  Claimed Tokens:"));
+    for (const token of result.claimTokenList) {
+      console.log(source_default.gray(`    ${token.tokenAmount} ${token.tokenSymbol} (${token.tokenAddress})`));
+    }
+    console.log();
+  }
+  if (result.txList.length > 0) {
+    console.log(source_default.white.bold("  Transactions:"));
+    for (const tx of result.txList) {
+      const statusLabel = tx.status === 1 ? source_default.green("Success") : tx.status === 2 ? source_default.red("Failed") : source_default.yellow("Sent");
+      console.log(source_default.gray(`    ${tx.txSignature} ${statusLabel}`));
+      console.log(source_default.blue(`    https://solscan.io/tx/${tx.txSignature}`));
+    }
+    console.log();
+  }
+}
 
 // src/cli/commands/pools.ts
 async function listPools2(options, globalOptions) {
@@ -84072,7 +84106,7 @@ byreal-cli catalog show dex.pool.list
 | dex.token.list | Query tokens with search |
 | dex.overview.global | Global statistics |
 | dex.swap.execute | Preview or execute a token swap |
-| dex.position.list | List user's CLMM positions |
+| dex.position.list | List positions for your wallet or any wallet via --user |
 | dex.position.analyze | Analyze existing position |
 | dex.position.open | Open a new CLMM position |
 | dex.position.increase | Add liquidity to an existing position |
@@ -84354,12 +84388,13 @@ byreal-cli swap execute --input-mint So11111111111111111111111111111111111111112
 \`\`\`
 
 ### positions list
-List user's CLMM positions.
+List CLMM positions for your wallet or any wallet address. Use \`--user\` to query another wallet's positions (read-only, no \`--wallet-address\` needed).
 
 \`\`\`bash
 byreal-cli positions list [options]
 
 Options:
+  --user <address>       Query positions for a specific wallet address (read-only)
   --page <n>             Page number (default: 1)
   --page-size <n>        Page size (default: 20)
   --sort-field <field>   Sort field
@@ -84368,6 +84403,18 @@ Options:
   --status <status>      Filter by status: 0=closed, 1=active
 \`\`\`
 
+Examples:
+\`\`\`bash
+# List your own positions
+byreal-cli positions list --wallet-address <your-addr> -o json
+
+# Query another user's positions (for LP copy trading research)
+byreal-cli positions list --user <target-wallet> -o json
+
+# Query another user's positions in a specific pool
+byreal-cli positions list --user <target-wallet> --pool <pool-address> -o json
+\`\`\`
+
 ### positions open
 Open a new CLMM position. Supports two modes: specify token amount (--amount) or USD investment (--amount-usd).
 
@@ -84502,6 +84549,9 @@ Options:
 - **Incentive rewards** \u2192 \`positions claim-rewards\` (this command)
 - **Copy bonus** \u2192 \`positions claim-bonus\` (see below)
 
+**IMPORTANT \u2014 claim-rewards is a multi-step flow:**
+The output includes \`orderCode\` and per-transaction \`txCode\`. After the wallet signs each transaction, you MUST call \`positions submit-rewards\` to send the signed transactions back to the backend for broadcasting. See "Workflow: Claim Rewards / Bonus" below.
+
 ### positions claim-bonus
 Claim CopyFarmer bonus rewards earned from copying other users' positions. Bonuses accrue in epochs and become claimable in time windows.
 
@@ -84517,6 +84567,24 @@ Options:
 - **Pending**: Settlement period, not yet claimable
 - **Claimable**: Ready to claim within the time window
 
+**IMPORTANT \u2014 claim-bonus is a multi-step flow** (same as claim-rewards): After signing, call \`positions submit-rewards\` to complete the claim.
+
+### positions submit-rewards
+Submit signed reward/bonus claim transactions to the backend for on-chain broadcasting. This is the final step after \`claim-rewards\` or \`claim-bonus\` generates unsigned transactions and the wallet signs them.
+
+\`\`\`bash
+byreal-cli positions submit-rewards [options]
+
+Options:
+  --order-code <code>         Order code from claim-rewards or claim-bonus output (required)
+  --signed-payloads <json>    JSON array of signed transactions (required)
+\`\`\`
+
+The \`--signed-payloads\` format:
+\`\`\`json
+[{"txCode":"<from output>","poolAddress":"<from output>","signedTx":"<base64 signed tx>"}]
+\`\`\`
+
 ### positions top-positions
 Query top positions in a pool. Use this to discover high-performing positions that can be copied.
 Each position includes an \`inRange\` field (true/false) indicating whether the pool's current tick is within the position's tick range. Out-of-range positions earn zero trading fees.
@@ -84693,6 +84761,43 @@ When user asks vague questions like "\u6709\u4EC0\u4E48\u4ED3\u4F4D\u53EF\u4EE5
 - Always explain WHY you recommend a position (e.g., "\u9AD8\u624B\u7EED\u8D39\u6536\u76CA + \u4F4E\u65E0\u5E38\u635F\u5931 + \u5728\u533A\u95F4\u5185")
 - If user's balance is low (<$20), suggest starting with a single position to minimize gas cost
 - If all positions in a pool are out-of-range, skip that pool and explain why
+- To inspect a specific LP's full portfolio: \`byreal-cli positions list --user <wallet-address> -o json\`
+
+## Workflow: Claim Rewards / Bonus (Multi-Step)
+
+Claiming incentive rewards (\`claim-rewards\`) and CopyFarmer bonus (\`claim-bonus\`) requires a **3-step flow** because the backend co-signs and broadcasts these transactions:
+
+**Step 1 \u2014 Preview** (optional but recommended):
+\`\`\`bash
+byreal-cli positions claim-rewards --dry-run --wallet-address <addr> -o json
+\`\`\`
+
+**Step 2 \u2014 Generate unsigned transactions**:
+\`\`\`bash
+byreal-cli positions claim-rewards --wallet-address <addr> -o json
+\`\`\`
+Output:
+\`\`\`json
+{
+  "orderCode": "ORD_xxx",
+  "unsignedTransactions": [
+    { "poolAddress": "...", "txPayload": "<base64>", "txCode": "TX_xxx", "tokens": [...] }
+  ]
+}
+\`\`\`
+
+**Step 3 \u2014 Sign each \`txPayload\` with the user's wallet**, then submit:
+\`\`\`bash
+byreal-cli positions submit-rewards \\
+  --order-code "ORD_xxx" \\
+  --signed-payloads '[{"txCode":"TX_xxx","poolAddress":"...","signedTx":"<base64 signed>"}]' \\
+  --wallet-address <addr> -o json
+\`\`\`
+The backend broadcasts the signed transactions on-chain and returns tx signatures + status.
+
+**For claim-bonus**: Same flow \u2014 replace \`claim-rewards\` with \`claim-bonus\` in Step 1-2; Step 3 is identical (\`submit-rewards\`).
+
+**Critical**: Do NOT skip Step 3. Without \`submit-rewards\`, the signed transactions are never sent to the blockchain. The \`orderCode\` ties the encode and submit steps together \u2014 always pass the same \`orderCode\` from Step 2 into Step 3.
 
 ## Output Format
 
@@ -84945,11 +85050,12 @@ var CAPABILITIES = [
   {
     id: "dex.position.list",
     name: "List Positions",
-    description: "List user CLMM positions with filtering and sorting. Requires --wallet-address global option.",
+    description: "List CLMM positions for your wallet or any wallet address. Use --user to query another wallet (read-only, no --wallet-address needed).",
     category: "query",
-    auth_required: true,
-    command: "byreal-cli positions list --wallet-address <address>",
+    auth_required: false,
+    command: "byreal-cli positions list",
     params: [
+      { name: "user", type: "string", required: false, description: "Query positions for a specific wallet address (read-only)" },
       { name: "page", type: "integer", required: false, description: "Page number", default: "1" },
       { name: "page-size", type: "integer", required: false, description: "Page size", default: "20" },
       { name: "sort-field", type: "string", required: false, description: "Sort field" },
@@ -85067,6 +85173,18 @@ var CAPABILITIES = [
       { name: "dry-run", type: "boolean", required: false, description: "Preview claimable bonus without claiming" }
     ]
   },
+  {
+    id: "dex.position.submitRewards",
+    name: "Submit Signed Rewards",
+    description: "Submit signed reward/bonus claim transactions to backend for broadcasting. Used after claim-rewards or claim-bonus generates unsigned transactions and the external wallet signs them. Requires --wallet-address global option.",
+    category: "execute",
+    auth_required: true,
+    command: "byreal-cli positions submit-rewards --wallet-address <address>",
+    params: [
+      { name: "order-code", type: "string", required: true, description: "Order code from claim-rewards or claim-bonus output" },
+      { name: "signed-payloads", type: "string", required: true, description: 'JSON array of signed transactions: [{"txCode":"...","poolAddress":"...","signedTx":"<base64>"}]' }
+    ]
+  },
   {
     id: "dex.position.topPositions",
     name: "Top Positions",
@@ -85620,25 +85738,31 @@ function serializeTransaction(tx) {
 // src/cli/commands/positions.ts
 init_errors();
 function createPositionsListCommand() {
-  return new Command("list").description("List your positions").option("--page <n>", "Page number", "1").option("--page-size <n>", "Page size", "20").option("--sort-field <field>", "Sort field").option("--sort-type <type>", "Sort direction: asc or desc").option("--pool <address>", "Filter by pool address").option(
+  return new Command("list").description("List positions for your wallet or any wallet address").option("--user <address>", "Query positions for a specific wallet address (read-only, no --wallet-address needed)").option("--page <n>", "Page number", "1").option("--page-size <n>", "Page size", "20").option("--sort-field <field>", "Sort field").option("--sort-type <type>", "Sort direction: asc or desc").option("--pool <address>", "Filter by pool address").option(
     "--status <status>",
     "Filter by status: 0=active, 1=closed (default: 0)"
   ).action(async (options, cmdObj) => {
     const globalOptions = cmdObj.optsWithGlobals();
     const format = globalOptions.output;
     const startTime = Date.now();
-    const walletAddress = globalOptions.walletAddress;
-    if (!walletAddress) {
-      const err2 = missingWalletAddressError();
+    const userAddress = options.user || globalOptions.walletAddress;
+    if (!userAddress) {
+      const errMsg = "Provide --user <address> or global --wallet-address to specify which wallet to query.";
       if (format === "json") {
-        outputErrorJson(err2.toJSON());
+        outputErrorJson({ code: "MISSING_ADDRESS", type: "VALIDATION", message: errMsg, retryable: false });
       } else {
-        outputErrorTable(err2.toJSON());
+        console.error(source_default.red(`
+Error: ${errMsg}`));
       }
       process.exit(1);
     }
+    if (options.user && format !== "json") {
+      console.log(source_default.gray(`
+  Positions for: ${options.user}
+`));
+    }
     const result = await api.listPositions({
-      userAddress: walletAddress,
+      userAddress,
       page: parseInt(options.page, 10),
       pageSize: parseInt(options.pageSize, 10),
       sortField: options.sortField,
@@ -87500,6 +87624,77 @@ SDK Error: ${message}`));
     }
   });
 }
+function createSubmitRewardsCommand() {
+  return new Command("submit-rewards").description(
+    "Submit signed reward/bonus transactions to backend for broadcasting"
+  ).requiredOption(
+    "--order-code <code>",
+    "Order code from claim-rewards or claim-bonus output"
+  ).requiredOption(
+    "--signed-payloads <json>",
+    'JSON array: [{"txCode":"...","poolAddress":"...","signedTx":"<base64>"}]'
+  ).action(async (options, cmdObj) => {
+    const globalOptions = cmdObj.optsWithGlobals();
+    const format = globalOptions.output;
+    const startTime = Date.now();
+    const walletAddress = globalOptions.walletAddress;
+    if (!walletAddress) {
+      const err2 = missingWalletAddressError();
+      if (format === "json") {
+        outputErrorJson(err2.toJSON());
+      } else {
+        outputErrorTable(err2.toJSON());
+      }
+      process.exit(1);
+    }
+    let signedPayloads;
+    try {
+      signedPayloads = JSON.parse(options.signedPayloads);
+      if (!Array.isArray(signedPayloads) || signedPayloads.length === 0) {
+        throw new Error("must be a non-empty array");
+      }
+      for (const p of signedPayloads) {
+        if (!p.txCode || !p.poolAddress || !p.signedTx) {
+          throw new Error(
+            "each entry must have txCode, poolAddress, signedTx"
+          );
+        }
+      }
+    } catch (e) {
+      const errMsg = `Invalid --signed-payloads: ${e.message}`;
+      if (format === "json") {
+        outputErrorJson({
+          code: "INVALID_PARAMETER",
+          type: "VALIDATION",
+          message: errMsg,
+          retryable: false
+        });
+      } else {
+        console.error(source_default.red(`
+Error: ${errMsg}`));
+      }
+      process.exit(1);
+    }
+    const orderResult = await api.submitRewardOrder({
+      orderCode: options.orderCode,
+      walletAddress,
+      signedTxPayload: signedPayloads
+    });
+    if (!orderResult.ok) {
+      if (format === "json") {
+        outputErrorJson(orderResult.error);
+      } else {
+        outputErrorTable(orderResult.error);
+      }
+      process.exit(1);
+    }
+    if (format === "json") {
+      outputJson(orderResult.value, startTime);
+    } else {
+      outputRewardOrderResult(orderResult.value);
+    }
+  });
+}
 function createPositionsCommand() {
   const cmd = new Command("positions").description("Manage CLMM positions");
   cmd.addCommand(createPositionsListCommand());
@@ -87510,6 +87705,7 @@ function createPositionsCommand() {
   cmd.addCommand(createPositionsClaimCommand());
   cmd.addCommand(createPositionsClaimRewardsCommand());
   cmd.addCommand(createPositionsClaimBonusCommand());
+  cmd.addCommand(createSubmitRewardsCommand());
   cmd.addCommand(createPositionsAnalyzeCommand());
   cmd.addCommand(createTopPositionsCommand());
   cmd.addCommand(createCopyPositionCommand());

package/package.json

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