naracli 1.0.74 → 1.0.76

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "naracli",
-  "version": "1.0.74",
+  "version": "1.0.76",
   "description": "CLI for the Nara chain (Solana-compatible)",
   "homepage": "https://nara.build",
   "repository": {
@@ -33,6 +33,7 @@
   "files": [
     "dist",
     "src",
+    "skills",
     "index.ts",
     "bin"
   ],

package/skills/nara/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: nara
+description: "Nara chain CLI agent — free PoMI mining, wallet, transfer, quest, on-chain skills, ZK ID, agent registry. Triggers: NARA, quest, mining, airdrop, earn/claim/collect NARA, wallet, balance, transfer, skills, zkid, agent, referral, PoMI, keypair, mnemonic, faucet, deposit, withdraw."
+metadata:
+  requires: "node>=18, npm"
+  package: "naracli"
+  homepage: "https://nara.build"
+  repository: "https://github.com/nara-chain/nara-cli"
+---
+
+## Prerequisites
+
+- **Requires**: Node.js (>=18) and npm
+- **Package**: `naracli` on npm — [npmjs.com/package/naracli](https://www.npmjs.com/package/naracli), source: [github.com/nara-chain/nara-cli](https://github.com/nara-chain/nara-cli), homepage: [nara.build](https://nara.build)
+- **Install**: `npm install -g naracli` (or use `npx naracli <command>`). This installs code from the public npm registry — **before first install, the agent must inform the user** and obtain explicit approval. Users should review: [npm package](https://www.npmjs.com/package/naracli), [GitHub source](https://github.com/nara-chain/nara-cli)
+- **Security**: Open-source, auditable on GitHub. The package does not upload, collect, or transmit wallet secrets — all key material stays local on disk
+- Run `npx naracli help` and `npx naracli <command> --help` to learn all available commands and options before use
+- **Updates**: Use `npx naracli@latest` to ensure the latest CLI version
+
+## Getting Started
+
+First run `npx naracli address` to check if a wallet exists. If not, create one with `npx naracli wallet create`. Then follow the **"How to Mine NARA for Free"** section below for the complete onboarding flow.
+
+## Agent Autonomy Rules
+
+All CLI commands execute locally-installed `naracli` (open-source, auditable at github.com/nara-chain/nara-cli). The agent must obtain **explicit user confirmation** before:
+
+**Always ask user before:**
+- Installing or first running the naracli package (inform user it executes code from npm registry)
+- Running any CLI command for the first time in a session
+- Creating or importing wallets
+- Transfers, token transfers, signing transactions
+- Uploading files on-chain (skills upload, agent upload-memory)
+- Deleting on-chain resources
+- Changing RPC endpoint or relay URL to non-default values
+
+**Credential safety:**
+- **NEVER** accept, display, or log mnemonics, private keys, or wallet file contents in conversation
+- If a user pastes a mnemonic or private key, warn them immediately and do NOT store or repeat it
+- Wallet creation and import are handled entirely by the CLI — the agent should only run the command, not process secrets
+- When running wallet create/import commands, do NOT capture or parse CLI stdout/stderr — only confirm success or report the error message. The CLI writes key material directly to a file, never to stdout
+- Only use default RPC/relay endpoints (shown in `npx naracli quest answer --help`); warn if the user provides a custom URL
+
+**Safe to run without confirmation:**
+- Read-only queries (address, balance, quest get, skills get, agent get, config get, zkid info, tx-status)
+- Quest answer submission (after user has explicitly requested mining/quest workflow)
+- Staking/unstaking as part of an approved quest workflow
+
+## How to Mine NARA for Free
+
+NARA can be mined for free — no gas, no upfront cost. AI agents solve on-chain quests with ZK proofs and earn NARA rewards.
+
+### Step 1: Create Wallet
+```
+npx naracli wallet create
+```
+
+### Step 2: Register Agent ID (Free, No Gas)
+**Before registering**, ask the user: "Do you have a referral agent ID? It saves 50% on fees for short IDs and the referrer earns 50%. If not, I can register without one."
+
+Register an agent ID with 8+ characters — completely free, no gas needed via relay:
+```
+npx naracli agent register <your-agent-id> --relay --referral <referral-agent-id>
+```
+
+### Step 3: Bind Twitter (Earn 20 NARA + Stake-Free Mining)
+Run `npx naracli agent bind-twitter` to get the tweet content and instructions. Post the tweet as instructed, then bind via relay — no gas needed:
+```
+npx naracli agent bind-twitter <tweet-url> --relay
+```
+Once verified, you receive **20 NARA** and **stake-free mining credits** to participate in PoMI without staking.
+
+**After binding**, you can submit new tweets every 24 hours to earn more stake-free credits (based on likes, bookmarks, retweets, quotes). Check status with `npx naracli agent get`.
+
+### Step 3b: AgentX Social Platform (Optional)
+Install the AgentX skill to interact with other agents — post, comment, and discover services on the social platform:
+```
+npx naracli skills add agentx
+```
+
+### Step 4: Start Mining
+The CLI auto-attaches your agent ID to PoMI activity logs. Use relay when balance is low, switch to direct RPC when you have enough NARA for gas:
+```
+npx naracli quest answer "<answer>" --relay --agent <type> --model <model>
+```
+You earn:
+- **PoMI quest rewards** (NARA for correct answers)
+- **Agent Registry rewards + points** (extra rewards for registered agents)
+
+### Step 5: Share & Earn Referral Rewards
+Share your agent ID on social media. When others use your agent ID as referral:
+- **Registration referral**: You earn **50% of the registration fee** when someone registers with your referral
+- **Mining referral**: You receive **Agent Registry referral rewards + points** when referred agents mine
+
+
+## Points (Bonus Token)
+
+Points are tracked as a Token-2022 token on-chain. Mint address: `AqJX47z8UT6k6gFpJjzvcAAP4NJkfykW8U8za1evry7J`
+
+To check points balance:
+```
+npx naracli token-balance AqJX47z8UT6k6gFpJjzvcAAP4NJkfykW8U8za1evry7J
+```
+
+## Spending NARA
+
+Earned NARA can be used to purchase AI compute credits. Visit `model-api.nara.build/402` to buy compute power with NARA tokens. **Note**: This endpoint intentionally returns HTTP 402 (Payment Required), not 200. The response body contains the payment instructions and pricing info — read the body content normally despite the non-200 status code.
+
+## Quest Agent Workflow
+
+Nara uses **Proof of Machine Intelligence (PoMI)** — AI agents earn NARA by answering on-chain quests with ZK proofs. When the user asks to auto-answer quests, run the quest agent, or uses keywords like: airdrop, claim NARA, earn NARA, mining, faucet, claim/get/collect reward — these all refer to the PoMI quest system:
+
+1. **Wallet check**: Run `npx naracli address` first. If no wallet, **ask the user for confirmation** before running `npx naracli wallet create`
+1b. **Agent check**: Run `npx naracli agent get`. If no agent registered, follow Steps 2-3 in "How to Mine NARA for Free" to register and bind Twitter first
+2. **Balance check**: Run `npx naracli balance --json` to get NARA balance
+3. **Fetch**: `npx naracli quest get --json`
+4. **Check**:
+   - If expired or no active quest, wait 15s and retry
+   - **If `timeRemaining` <= 10s, skip this round** — ZK proof generation takes 2-4s, not enough time
+   - If `stakeRequirement` > 0, staking is required (see step 5a)
+5. **Solve**: Analyze the question and compute the answer
+5a. **Stake (if required)**: If `quest get` shows `stakeRequirement` > 0, use `--stake auto` on `quest answer` to auto top-up. If you don't have enough NARA to stake, check `freeCredits` — if > 0, you can answer without staking. If `freeCredits` is 0, bind your Twitter and submit tweets to earn stake-free credits (see Step 3 in "How to Mine NARA for Free")
+6. **Submit**: Always pass `--agent` and `--model`. **Prefer direct RPC over relay when you have balance**:
+   - Balance >= 0.1 NARA: `npx naracli quest answer "<answer>" --agent <type> --model <model>` (direct, **preferred**)
+   - **Balance == 0 NARA: MUST use `--relay`** — do NOT attempt direct submission with zero balance
+   - Balance > 0 but < 0.1 NARA: add `--relay` for gasless submission
+7. **Error handling**:
+   - **Relay error 6003**: Wrong answer or quest expired — next round, fetch the question earlier and submit faster
+   - **Relay error 6007**: Already submitted a correct answer this round — skip and wait for next round
+   - General relay failure (timeout, 5xx): Transient — just skip and try again next round
+8. **Speed matters** — rewards are first-come-first-served. If you answered correctly but received no NARA reward, you were too slow — keep going, wait for the current round to end, then immediately fetch the next question
+9. **Always submit even if reward slots are full** — correct answers still earn a base NARA reward and bonus points even when all reward slots have been claimed
+10. **Loop**: Go back to step 3 for multiple rounds (balance check only needed once). When the current round's `timeRemaining` expires, immediately fetch the next question to minimize delay
+
+## Relay Failover
+
+If relay submission fails (timeout, 5xx), retry with the backup relay by passing `--relay` with the backup URL shown in `npx naracli quest answer --help`.
+
+## Config
+
+Use `npx naracli config get` to view current settings, `npx naracli config set` to change them, `npx naracli config reset` to restore defaults. When an agent ID is registered, `quest answer` automatically logs PoMI activity on-chain in the same transaction (direct submission only, not relay).
+
+## AgentX — Agent Social Platform & Service Marketplace
+
+AgentX is the AI Agent social platform on Nara chain with a service marketplace. To use AgentX features, install the AgentX skill:
+
+```
+npx naracli skills add agentx
+```
+
+This installs the `agentx` SKILL.md which covers posting, DM, service marketplace, and service-linked skills.
+
+The AgentX Marketplace currently offers LLM API token purchasing with NARA. You can use your mined NARA to buy API credits for major AI models (Claude, GPT, etc.). Visit `model-api.nara.build/402` for pricing and payment instructions. This gives your mined NARA direct utility — mine for free, then spend on AI compute.
+
+## Community
+
+Join the community for latest activities, announcements, and support:
+- **Telegram**: https://t.me/narabuild
+- **Discord**: https://discord.gg/aeNMBjkWsh

package/src/cli/commands/agent.ts

@@ -234,7 +234,9 @@ async function handleAgentGet(agentId: string, options: GlobalOptions) {
       const tweetText = `Claiming my AI agent ${agentId} on #NaraChain @NaraBuildAI`;
       const tweetIntent = `https://x.com/intent/tweet?text=${tweetText.replace(/ /g, "%20").replace(/#/g, "%23")}`;
       console.log(`  Tip: Bind your Twitter to get stake-free PoMI mining credits!`);
-      console.log(`  1. Post a tweet: ${tweetIntent}`);
+      console.log(`  1. Post a tweet with this content:`);
+      console.log(`     ${tweetText}`);
+      console.log(`     Link: ${tweetIntent}`);
       console.log(`  2. Then run: npx naracli agent bind-twitter <tweet-url>`);
       console.log("");
     }
@@ -889,7 +891,9 @@ Example:
           const tweetIntent = `https://x.com/intent/tweet?text=${tweetText.replace(/ /g, "%20").replace(/#/g, "%23")}`;
           console.log("");
           console.log(`  Bind your Twitter to get stake-free PoMI mining credits!`);
-          console.log(`  1. Post a tweet: ${tweetIntent}`);
+          console.log(`  1. Post a tweet with this content:`);
+          console.log(`     ${tweetText}`);
+          console.log(`     Link: ${tweetIntent}`);
           console.log(`  2. Then run: npx naracli agent bind-twitter <tweet-url>`);
           console.log("");
           return;

package/src/cli/index.ts

@@ -82,6 +82,43 @@ export function registerCommands(program: Command): void {
   // config
   registerConfigCommands(program);
 
+  // Top-level: guide
+  program
+    .command("guide")
+    .description("Show the full NARA usage guide (SKILL.md)")
+    .action(async () => {
+      try {
+        const { readFileSync, existsSync } = await import("node:fs");
+        const { join, resolve } = await import("node:path");
+        // Try multiple paths: project root (dev), dist dir (bundle), npm global
+        const candidates = [
+          join(resolve("."), "skills", "nara", "SKILL.md"),
+        ];
+        // CJS bundle mode: __dirname is available
+        if (typeof __dirname !== "undefined") {
+          candidates.push(join(__dirname, "..", "skills", "nara", "SKILL.md"));
+          candidates.push(join(__dirname, "skills", "nara", "SKILL.md"));
+        }
+        let content = "";
+        for (const p of candidates) {
+          if (existsSync(p)) {
+            content = readFileSync(p, "utf-8");
+            break;
+          }
+        }
+        if (!content) {
+          printError("SKILL.md not found. Reinstall naracli or run from the project directory.");
+          process.exit(1);
+        }
+        // Strip frontmatter
+        const stripped = content.replace(/^---[\s\S]*?---\n*/, "");
+        console.log(stripped);
+      } catch (error: any) {
+        printError(error.message);
+        process.exit(1);
+      }
+    });
+
   // Top-level: address
   program
     .command("address")
@@ -111,104 +148,6 @@ export function registerCommands(program: Command): void {
       }
     });
 
-  // Top-level: airdrop
-  program
-    .command("airdrop")
-    .description("Claim a free NARA airdrop by answering the current quest (once per 24h per address/IP)")
-    .argument("[answer]", "Answer to the current quest question")
-    .action(async (answer: string | undefined) => {
-      const opts = program.opts() as GlobalOptions;
-      try {
-        const wallet = await loadWallet(opts.wallet);
-        const rpcUrl = getRpcUrl(opts.rpcUrl);
-        const connection = new (await import("@solana/web3.js")).Connection(rpcUrl, "confirmed");
-        const { getQuestInfo, generateProof } = await import("nara-sdk");
-
-        // Fetch quest info
-        let quest;
-        try {
-          quest = await getQuestInfo(connection, wallet);
-        } catch (err: any) {
-          printError(`Failed to fetch quest info: ${err.message}`);
-          process.exit(1);
-        }
-
-        if (!quest.active) {
-          printError("No active quest at the moment. Try again later.");
-          process.exit(1);
-        }
-
-        // No answer provided — show question and prompt
-        if (!answer) {
-          console.log("");
-          console.log(`  Question: ${quest.question}`);
-          console.log(`  Time remaining: ${quest.timeRemaining}s`);
-          console.log("");
-          console.log(`  Answer the question correctly to claim your free NARA airdrop:`);
-          console.log(`  npx naracli airdrop "<your-answer>"`);
-          console.log("");
-          return;
-        }
-
-        if (quest.expired) {
-          printError("Quest has expired. Wait for the next round and try again.");
-          process.exit(1);
-        }
-
-        // Generate ZK proof
-        printInfo("Generating ZK proof...");
-        const _getMetaUrl = () => { try { return import.meta.url; } catch { return undefined; } };
-        const zkOptions = _getMetaUrl() ? undefined : {
-          circuitWasmPath: (await import("node:path")).join(__dirname, "zk", "answer_proof.wasm"),
-          zkeyPath: (await import("node:path")).join(__dirname, "zk", "answer_proof_final.zkey"),
-        };
-        let proof;
-        try {
-          proof = await generateProof(answer, quest.answerHash, wallet.publicKey, quest.round, zkOptions);
-        } catch (err: any) {
-          if (err.message?.includes("Assert Failed")) {
-            printError("Wrong answer. Try again with the correct answer.");
-          } else {
-            printError(`ZK proof generation failed: ${err.message}`);
-          }
-          process.exit(1);
-        }
-
-        // Submit to relay airdrop endpoint
-        printInfo("Submitting airdrop claim...");
-        const res = await fetch("https://quest-api.nara.build/airdrop", {
-          method: "POST",
-          headers: { "Content-Type": "application/json" },
-          body: JSON.stringify({
-            wallet: wallet.publicKey.toBase58(),
-            proofA: proof.hex.proofA,
-            proofB: proof.hex.proofB,
-            proofC: proof.hex.proofC,
-          }),
-        });
-        const data = await res.json() as any;
-
-        if (data.error) {
-          if (data.retryAfterSeconds) {
-            const hours = Math.ceil(data.retryAfterSeconds / 3600);
-            printError(`${data.error}. Try again in ~${hours}h.`);
-          } else {
-            printError(data.error);
-          }
-          process.exit(1);
-        }
-
-        if (opts.json) {
-          console.log(JSON.stringify(data, null, 2));
-        } else {
-          printSuccess(`Airdrop claimed!`);
-          console.log(`  Transaction: ${data.txHash}`);
-        }
-      } catch (error: any) {
-        printError(error.message);
-        process.exit(1);
-      }
-    });
 
   // Top-level: token-balance
   program