naracli 1.0.55 → 1.0.57

package/bin/nara-cli.ts

@@ -15,13 +15,13 @@ const program = new Command();
 // Set program metadata
 program
   .name("naracli")
-  .description("CLI for the Nara chain (Solana-compatible)")
+  .description("CLI for the Nara chain. Native coin is NARA (not SOL). Mine NARA for free via PoMI quests, manage wallets, register agents, and more. Run 'naracli <command> --help' for details on any command.")
   .version(version);
 
 // Add global options
 program
-  .option("-r, --rpc-url <url>", "RPC endpoint URL")
-  .option("-w, --wallet <path>", "Path to wallet keypair JSON file")
+  .option("-r, --rpc-url <url>", "RPC endpoint (default: https://mainnet-api.nara.build/)")
+  .option("-w, --wallet <path>", "Path to wallet keypair JSON file (default: ~/.config/nara/id.json)")
   .option("-j, --json", "Output in JSON format");
 
 // Register all command modules

package/dist/nara-cli-bundle.cjs

@@ -130513,8 +130513,8 @@ ${result.base64}`);
 var _DEFAULT_WALLET_PATH = process.env.WALLET_PATH || "~/.config/nara/id.json";
 var DEFAULT_WALLET_PATH2 = _DEFAULT_WALLET_PATH.startsWith("~") ? (0, import_node_path3.join)((0, import_node_os3.homedir)(), _DEFAULT_WALLET_PATH.slice(1)) : _DEFAULT_WALLET_PATH;
 function registerWalletCommands(program3) {
-  const wallet = program3.command("wallet").description("Wallet management commands");
-  wallet.command("create").description("Create a new wallet").option("-o, --output <path>", "Output path for wallet file (default: ~/.config/nara/id.json)").action(async (options) => {
+  const wallet = program3.command("wallet").description("Wallet management \u2014 create or import a keypair for signing transactions");
+  wallet.command("create").description("Create a new wallet keypair (saved to ~/.config/nara/id.json by default)").option("-o, --output <path>", "Output path for wallet file (default: ~/.config/nara/id.json)").action(async (options) => {
     try {
       await handleWalletCreate(options);
     } catch (error) {
@@ -130580,7 +130580,12 @@ async function handleTokenBalance(tokenAddress, options) {
   }
   printInfo(`Owner: ${owner.toBase58()}`);
   printInfo(`Token: ${tokenAddress}`);
-  const tokenAccount = await getAssociatedTokenAddress(tokenMint, owner);
+  const mintAccountInfo = await connection.getAccountInfo(tokenMint);
+  if (!mintAccountInfo) {
+    throw new Error(`Token mint ${tokenAddress} not found on chain`);
+  }
+  const tokenProgramId = mintAccountInfo.owner.equals(TOKEN_2022_PROGRAM_ID) ? TOKEN_2022_PROGRAM_ID : TOKEN_PROGRAM_ID;
+  const tokenAccount = await getAssociatedTokenAddress(tokenMint, owner, true, tokenProgramId);
   try {
     const accountInfo = await connection.getTokenAccountBalance(tokenAccount);
     const balance = accountInfo.value;
@@ -131203,8 +131208,8 @@ function handleSubmitError(err) {
   process.exit(1);
 }
 function registerQuestCommands(program3) {
-  const quest = program3.command("quest").description("Quest commands");
-  quest.command("get").description("Get current quest info").action(async (_opts, cmd) => {
+  const quest = program3.command("quest").description("PoMI quest commands \u2014 mine NARA by answering on-chain quests with ZK proofs");
+  quest.command("get").description("Get current quest info (question, deadline, difficulty, stake requirement)").action(async (_opts, cmd) => {
     try {
       const globalOpts = cmd.optsWithGlobals();
       await handleQuestGet(globalOpts);
@@ -131213,7 +131218,7 @@ function registerQuestCommands(program3) {
       process.exit(1);
     }
   });
-  quest.command("answer <answer>").description("Submit an answer").option("--relay [url]", `Submit via relay service, gasless (default: ${DEFAULT_QUEST_RELAY_URL2})`).option("--agent <name>", "Agent identifier (default: naracli)").option("--model <name>", "Model identifier").option("--referral <agent-id>", "Referral agent ID").option("--stake [amount]", 'Stake NARA before answering ("auto" to top-up to requirement, or a number)').action(async (answer, opts, cmd) => {
+  quest.command("answer <answer>").description("Submit a quest answer with ZK proof. Generates a proof locally and submits on-chain. Use --relay when balance is 0 (gasless). Always pass --agent and --model for reward tracking.").option("--relay [url]", `Submit via gasless relay (default: ${DEFAULT_QUEST_RELAY_URL2}, backup: https://quest2-api.nara.build/)`).option("--agent <name>", "Agent/platform type: claude-code, cursor, chatgpt, openclaw, etc. (default: naracli)").option("--model <name>", "AI model used: claude-opus-4-6, claude-sonnet-4-6, gpt-4o, etc.").option("--referral <agent-id>", "Referral agent ID for earning referral points").option("--stake [amount]", 'Stake NARA in the same tx ("auto" to top-up to requirement, or an exact amount)').action(async (answer, opts, cmd) => {
     try {
       const globalOpts = cmd.optsWithGlobals();
       const relayUrl = opts.relay === true ? DEFAULT_QUEST_RELAY_URL2 : opts.relay;
@@ -133142,7 +133147,7 @@ async function handleSkillsDelete(name, options) {
   }
 }
 function registerSkillsCommands(program3) {
-  const skills = program3.command("skills").description("Skills hub commands");
+  const skills = program3.command("skills").description("On-chain skill registry \u2014 register, publish, install, and manage AI agent skills");
   skills.command("register <name> <author>").description("Register a new skill on-chain").action(async (name, author, _opts, cmd) => {
     try {
       const globalOpts = cmd.optsWithGlobals();
@@ -133808,8 +133813,8 @@ async function handleAgentClear(options) {
   }
 }
 function registerAgentCommands(program3) {
-  const agent = program3.command("agent").description("Agent Registry commands (on-chain AI agents)");
-  agent.command("register <agent-id>").description("Register a new agent on-chain").option("--referral <agent-id>", "Referral agent ID").action(async (agentId, opts, cmd) => {
+  const agent = program3.command("agent").description("Agent Registry \u2014 register an on-chain AI agent identity to earn extra rewards and points from PoMI mining");
+  agent.command("register <agent-id>").description("Register a new agent on-chain (costs 1 NARA, 50% off with referral). Agent ID must be lowercase alphanumeric with hyphens.").option("--referral <agent-id>", "Referral agent ID \u2014 saves 50% on registration fee").action(async (agentId, opts, cmd) => {
     try {
       const globalOpts = cmd.optsWithGlobals();
       await handleAgentRegister(agentId, { ...globalOpts, ...opts });
@@ -134043,7 +134048,7 @@ function registerCommands(program3) {
   registerZkIdCommands(program3);
   registerAgentCommands(program3);
   registerConfigCommands(program3);
-  program3.command("address").description("Show wallet address").action(async () => {
+  program3.command("address").description("Show wallet public address (run this first to check if a wallet exists)").action(async () => {
     const opts = program3.opts();
     try {
       await handleWalletAddress(opts);
@@ -134052,7 +134057,7 @@ function registerCommands(program3) {
       process.exit(1);
     }
   });
-  program3.command("balance").description("Check NARA balance").argument("[address]", "Wallet address (optional, defaults to current wallet)").action(async (address) => {
+  program3.command("balance").description("Check NARA balance (native coin, not SOL)").argument("[address]", "Wallet address (optional, defaults to current wallet)").action(async (address) => {
     const opts = program3.opts();
     try {
       await handleWalletBalance(address, opts);
@@ -134061,7 +134066,7 @@ function registerCommands(program3) {
       process.exit(1);
     }
   });
-  program3.command("token-balance <token-address>").description("Check token balance").option("--owner <address>", "Owner address (optional, defaults to current wallet)").action(async (tokenAddress, options) => {
+  program3.command("token-balance <token-address>").description("Check token balance (supports SPL Token and Token-2022)").option("--owner <address>", "Owner address (optional, defaults to current wallet)").action(async (tokenAddress, options) => {
     const opts = program3.opts();
     try {
       await handleTokenBalance(tokenAddress, { ...opts, ...options });
@@ -134118,7 +134123,7 @@ function registerCommands(program3) {
       process.exit(1);
     }
   });
-  program3.command("sign <base64-tx>").description("Sign a base64-encoded transaction").option("--send", "Send the signed transaction", false).action(async (base64Tx, options) => {
+  program3.command("sign <base64-tx>").description("Sign a base64-encoded transaction (supports legacy and versioned transactions)").option("--send", "Sign and broadcast the transaction on-chain", false).action(async (base64Tx, options) => {
     const opts = program3.opts();
     try {
       const wallet = await loadWallet(opts.wallet);
@@ -134169,10 +134174,10 @@ function registerCommands(program3) {
 }
 
 // bin/nara-cli.ts
-var version2 = true ? "1.0.55" : "dev";
+var version2 = true ? "1.0.57" : "dev";
 var program2 = new Command();
-program2.name("naracli").description("CLI for the Nara chain (Solana-compatible)").version(version2);
-program2.option("-r, --rpc-url <url>", "RPC endpoint URL").option("-w, --wallet <path>", "Path to wallet keypair JSON file").option("-j, --json", "Output in JSON format");
+program2.name("naracli").description("CLI for the Nara chain. Native coin is NARA (not SOL). Mine NARA for free via PoMI quests, manage wallets, register agents, and more. Run 'naracli <command> --help' for details on any command.").version(version2);
+program2.option("-r, --rpc-url <url>", "RPC endpoint (default: https://mainnet-api.nara.build/)").option("-w, --wallet <path>", "Path to wallet keypair JSON file (default: ~/.config/nara/id.json)").option("-j, --json", "Output in JSON format");
 registerCommands(program2);
 if (!process.argv.slice(2).length) {
   program2.outputHelp();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "naracli",
-  "version": "1.0.55",
+  "version": "1.0.57",
   "description": "CLI for the Nara chain (Solana-compatible)",
   "homepage": "https://nara.build",
   "repository": {

package/src/cli/commands/agent.ts

@@ -304,13 +304,13 @@ async function handleAgentClear(options: GlobalOptions) {
 export function registerAgentCommands(program: Command): void {
   const agent = program
     .command("agent")
-    .description("Agent Registry commands (on-chain AI agents)");
+    .description("Agent Registry — register an on-chain AI agent identity to earn extra rewards and points from PoMI mining");
 
   // agent register
   agent
     .command("register <agent-id>")
-    .description("Register a new agent on-chain")
-    .option("--referral <agent-id>", "Referral agent ID")
+    .description("Register a new agent on-chain (costs 1 NARA, 50% off with referral). Agent ID must be lowercase alphanumeric with hyphens.")
+    .option("--referral <agent-id>", "Referral agent ID — saves 50% on registration fee")
     .action(async (agentId: string, opts: { referral?: string }, cmd: Command) => {
       try {
         const globalOpts = cmd.optsWithGlobals() as GlobalOptions;

package/src/cli/commands/quest.ts

@@ -400,12 +400,12 @@ function handleSubmitError(err: any) {
 export function registerQuestCommands(program: Command): void {
   const quest = program
     .command("quest")
-    .description("Quest commands");
+    .description("PoMI quest commands — mine NARA by answering on-chain quests with ZK proofs");
 
   // quest get
   quest
     .command("get")
-    .description("Get current quest info")
+    .description("Get current quest info (question, deadline, difficulty, stake requirement)")
     .action(async (_opts: any, cmd: Command) => {
       try {
         const globalOpts = cmd.optsWithGlobals() as GlobalOptions;
@@ -419,12 +419,12 @@ export function registerQuestCommands(program: Command): void {
   // quest answer
   quest
     .command("answer <answer>")
-    .description("Submit an answer")
-    .option("--relay [url]", `Submit via relay service, gasless (default: ${DEFAULT_QUEST_RELAY_URL})`)
-    .option("--agent <name>", "Agent identifier (default: naracli)")
-    .option("--model <name>", "Model identifier")
-    .option("--referral <agent-id>", "Referral agent ID")
-    .option("--stake [amount]", 'Stake NARA before answering ("auto" to top-up to requirement, or a number)')
+    .description("Submit a quest answer with ZK proof. Generates a proof locally and submits on-chain. Use --relay when balance is 0 (gasless). Always pass --agent and --model for reward tracking.")
+    .option("--relay [url]", `Submit via gasless relay (default: ${DEFAULT_QUEST_RELAY_URL}, backup: https://quest2-api.nara.build/)`)
+    .option("--agent <name>", "Agent/platform type: claude-code, cursor, chatgpt, openclaw, etc. (default: naracli)")
+    .option("--model <name>", "AI model used: claude-opus-4-6, claude-sonnet-4-6, gpt-4o, etc.")
+    .option("--referral <agent-id>", "Referral agent ID for earning referral points")
+    .option("--stake [amount]", 'Stake NARA in the same tx ("auto" to top-up to requirement, or an exact amount)')
     .action(async (answer: string, opts: any, cmd: Command) => {
       try {
         const globalOpts = cmd.optsWithGlobals() as GlobalOptions;

package/src/cli/commands/skills.ts

@@ -281,7 +281,7 @@ async function handleSkillsDelete(name: string, options: GlobalOptions & { yes?:
 export function registerSkillsCommands(program: Command): void {
   const skills = program
     .command("skills")
-    .description("Skills hub commands");
+    .description("On-chain skill registry — register, publish, install, and manage AI agent skills");
 
   // skills register
   skills

package/src/cli/commands/wallet.ts

@@ -14,6 +14,7 @@ import {
   getAssociatedTokenAddress,
   createTransferInstruction,
   TOKEN_PROGRAM_ID,
+  TOKEN_2022_PROGRAM_ID,
 } from "@solana/spl-token";
 import * as bip39 from "bip39";
 import { derivePath } from "ed25519-hd-key";
@@ -54,12 +55,12 @@ const DEFAULT_WALLET_PATH = _DEFAULT_WALLET_PATH.startsWith("~")
 export function registerWalletCommands(program: Command): void {
   const wallet = program
     .command("wallet")
-    .description("Wallet management commands");
+    .description("Wallet management — create or import a keypair for signing transactions");
 
   // wallet create
   wallet
     .command("create")
-    .description("Create a new wallet")
+    .description("Create a new wallet keypair (saved to ~/.config/nara/id.json by default)")
     .option("-o, --output <path>", "Output path for wallet file (default: ~/.config/nara/id.json)")
     .action(async (options: { output?: string }) => {
       try {
@@ -176,8 +177,17 @@ export async function handleTokenBalance(
   printInfo(`Owner: ${owner.toBase58()}`);
   printInfo(`Token: ${tokenAddress}`);
 
+  // Detect token program (SPL Token vs Token-2022) by checking mint account owner
+  const mintAccountInfo = await connection.getAccountInfo(tokenMint);
+  if (!mintAccountInfo) {
+    throw new Error(`Token mint ${tokenAddress} not found on chain`);
+  }
+  const tokenProgramId = mintAccountInfo.owner.equals(TOKEN_2022_PROGRAM_ID)
+    ? TOKEN_2022_PROGRAM_ID
+    : TOKEN_PROGRAM_ID;
+
   // Get associated token account
-  const tokenAccount = await getAssociatedTokenAddress(tokenMint, owner);
+  const tokenAccount = await getAssociatedTokenAddress(tokenMint, owner, true, tokenProgramId);
 
   // Get token account balance
   try {

package/src/cli/index.ts

@@ -85,7 +85,7 @@ export function registerCommands(program: Command): void {
   // Top-level: address
   program
     .command("address")
-    .description("Show wallet address")
+    .description("Show wallet public address (run this first to check if a wallet exists)")
     .action(async () => {
       const opts = program.opts() as GlobalOptions;
       try {
@@ -99,7 +99,7 @@ export function registerCommands(program: Command): void {
   // Top-level: balance
   program
     .command("balance")
-    .description("Check NARA balance")
+    .description("Check NARA balance (native coin, not SOL)")
     .argument("[address]", "Wallet address (optional, defaults to current wallet)")
     .action(async (address: string | undefined) => {
       const opts = program.opts() as WalletBalanceOptions;
@@ -114,7 +114,7 @@ export function registerCommands(program: Command): void {
   // Top-level: token-balance
   program
     .command("token-balance <token-address>")
-    .description("Check token balance")
+    .description("Check token balance (supports SPL Token and Token-2022)")
     .option("--owner <address>", "Owner address (optional, defaults to current wallet)")
     .action(async (tokenAddress: string, options: { owner?: string }) => {
       const opts = program.opts() as TokenBalanceOptions;
@@ -199,8 +199,8 @@ export function registerCommands(program: Command): void {
   // Top-level: sign
   program
     .command("sign <base64-tx>")
-    .description("Sign a base64-encoded transaction")
-    .option("--send", "Send the signed transaction", false)
+    .description("Sign a base64-encoded transaction (supports legacy and versioned transactions)")
+    .option("--send", "Sign and broadcast the transaction on-chain", false)
     .action(async (base64Tx: string, options: { send?: boolean }) => {
       const opts = program.opts() as GlobalOptions;
       try {