@axon-chain/axon-skills 0.1.0

package/README.md

@@ -0,0 +1,42 @@
+# @axon-chain/axon-skills
+
+Install official Axon skills for OpenClaw and the global skills root with `npx`.
+
+## Included skills
+
+- `axon-validator-node`: Axon mainnet validator and sync-node operations
+- `axon-mainnet-user`: Axon mainnet wallet and public RPC usage
+
+## Install
+
+```bash
+npx @axon-chain/axon-skills install validator
+npx @axon-chain/axon-skills install user
+npx @axon-chain/axon-skills install all
+```
+
+Default installs update both roots:
+
+- `${OPENCLAW_STATE_DIR:-~/.openclaw}/skills`
+- `${AGENTS_SKILLS_DIR:-${AGENTS_HOME:-~/.agents}/skills}`
+
+Repeat installs update existing skill folders in place.
+
+## Commands
+
+```bash
+npx @axon-chain/axon-skills list
+npx @axon-chain/axon-skills install validator
+npx @axon-chain/axon-skills install user
+npx @axon-chain/axon-skills install all
+npx @axon-chain/axon-skills install all --dry-run
+npx @axon-chain/axon-skills install validator --dest /path/to/skills
+```
+
+## Verify
+
+```bash
+openclaw skills list
+```
+
+If OpenClaw is not installed on the current machine, inspect the installed skill folders directly under the target roots.

package/bin/axon-skills.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+
+import { runCli } from "../lib/cli.js";
+
+try {
+  const exitCode = await runCli(process.argv.slice(2));
+  process.exitCode = exitCode;
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  process.stderr.write(`${message}\n`);
+  process.exitCode = 1;
+}

package/lib/catalog.js

@@ -0,0 +1,54 @@
+export const SKILL_CATALOG = Object.freeze({
+  validator: Object.freeze({
+    key: "validator",
+    packageDir: "axon-validator-node",
+    skillName: "axon-validator-node",
+    summary: "Official Axon mainnet validator and node-operator workflow."
+  }),
+  user: Object.freeze({
+    key: "user",
+    packageDir: "axon-mainnet-user",
+    skillName: "axon-mainnet-user",
+    summary: "Ordinary Axon mainnet wallet and chain-usage workflow."
+  })
+});
+
+export const LIST_TARGETS = Object.freeze([
+  SKILL_CATALOG.validator,
+  SKILL_CATALOG.user,
+  Object.freeze({
+    key: "all",
+    packageDir: null,
+    skillName: null,
+    summary: "Install both skills."
+  })
+]);
+
+export function resolveInstallTargets(requested) {
+  const normalized = String(requested || "").trim().toLowerCase();
+
+  if (!normalized) {
+    throw new Error("Missing install target. Use one of: validator, user, all.");
+  }
+
+  if (normalized === "all") {
+    return [SKILL_CATALOG.validator, SKILL_CATALOG.user];
+  }
+
+  for (const entry of Object.values(SKILL_CATALOG)) {
+    if (normalized === entry.key || normalized === entry.skillName) {
+      return [entry];
+    }
+  }
+
+  throw new Error(`Unknown install target "${requested}". Use one of: validator, user, all.`);
+}
+
+export function formatList() {
+  return [
+    "Available install targets:",
+    "validator\tOfficial Axon mainnet validator and node-operator workflow",
+    "user\tOrdinary Axon mainnet wallet and chain-usage workflow",
+    "all\tInstall both skills"
+  ].join("\n");
+}

package/lib/cli.js

@@ -0,0 +1,126 @@
+import { formatList } from "./catalog.js";
+import { installSkills } from "./install.js";
+
+function buildHelpText() {
+  return [
+    "Usage:",
+    "  axon-skills list",
+    "  axon-skills install <validator|user|all> [--dest <dir>] [--force] [--dry-run]",
+    "",
+    "Examples:",
+    "  npx @axon-chain/axon-skills list",
+    "  npx @axon-chain/axon-skills install validator",
+    "  npx @axon-chain/axon-skills install all --force",
+    "",
+    "Default install roots:",
+    "  ${OPENCLAW_STATE_DIR:-~/.openclaw}/skills",
+    "  ${AGENTS_SKILLS_DIR:-${AGENTS_HOME:-~/.agents}/skills}",
+    "",
+    "Repeat installs update existing skill folders in place."
+  ].join("\n");
+}
+
+function parseInstallArgs(args) {
+  const parsed = {
+    requested: args[0],
+    destRoot: null,
+    force: false,
+    dryRun: false
+  };
+
+  for (let index = 1; index < args.length; index += 1) {
+    const current = args[index];
+
+    if (current === "--force") {
+      parsed.force = true;
+      continue;
+    }
+
+    if (current === "--dry-run") {
+      parsed.dryRun = true;
+      continue;
+    }
+
+    if (current === "--dest") {
+      index += 1;
+      if (index >= args.length) {
+        throw new Error("Missing value after --dest.");
+      }
+      parsed.destRoot = args[index];
+      continue;
+    }
+
+    if (current === "--help" || current === "-h") {
+      parsed.help = true;
+      continue;
+    }
+
+    throw new Error(`Unknown option: ${current}`);
+  }
+
+  return parsed;
+}
+
+function write(stream, text) {
+  stream.write(`${text}\n`);
+}
+
+export async function runCli(
+  argv,
+  options = {}
+) {
+  const stdout = options.stdout ?? process.stdout;
+  const stderr = options.stderr ?? process.stderr;
+  const env = options.env ?? process.env;
+  const homedir = options.homedir;
+  const packageRoot = options.packageRoot;
+
+  const args = Array.isArray(argv) ? argv : [];
+  const command = args[0];
+
+  if (!command || command === "--help" || command === "-h" || command === "help") {
+    write(stdout, buildHelpText());
+    return 0;
+  }
+
+  if (command === "list") {
+    write(stdout, formatList());
+    return 0;
+  }
+
+  if (command === "install") {
+    const parsed = parseInstallArgs(args.slice(1));
+    if (parsed.help) {
+      write(stdout, buildHelpText());
+      return 0;
+    }
+
+    const result = await installSkills({
+      requested: parsed.requested,
+      destRoot: parsed.destRoot,
+      force: parsed.force,
+      dryRun: parsed.dryRun,
+      env,
+      homedir,
+      packageRoot
+    });
+
+    const actionLabel = result.dryRun ? "Planned installs:" : "Installed skills:";
+    write(stdout, actionLabel);
+    for (const item of result.installed) {
+      write(stdout, `- ${item.skillName} -> ${item.finalDir}`);
+    }
+    write(stdout, "");
+    write(stdout, "Install roots:");
+    for (const root of result.destinationRoots) {
+      write(stdout, `- ${root}`);
+    }
+    write(stdout, "Verify with: openclaw skills list");
+    write(stdout, "Global skills live under the .agents skills root.");
+    return 0;
+  }
+
+  write(stderr, `Unknown command: ${command}`);
+  write(stderr, buildHelpText());
+  return 1;
+}

package/lib/install.js

@@ -0,0 +1,175 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { resolveInstallTargets } from "./catalog.js";
+
+export function resolvePackageRoot(metaUrl = import.meta.url) {
+  return path.resolve(path.dirname(fileURLToPath(metaUrl)), "..");
+}
+
+export function resolveHomeDir(env = process.env, homedir = os.homedir) {
+  const explicit = env.HOME?.trim() || env.USERPROFILE?.trim();
+  if (explicit) {
+    return path.resolve(explicit);
+  }
+  return path.resolve(homedir());
+}
+
+export function expandUserPath(input, env = process.env, homedir = os.homedir) {
+  const raw = String(input || "").trim();
+  if (!raw) {
+    throw new Error("Destination path must not be empty.");
+  }
+
+  if (raw === "~") {
+    return resolveHomeDir(env, homedir);
+  }
+
+  if (raw.startsWith("~/")) {
+    return path.join(resolveHomeDir(env, homedir), raw.slice(2));
+  }
+
+  return path.resolve(raw);
+}
+
+export function resolveDefaultSkillsRoot(options = {}) {
+  const env = options.env ?? process.env;
+  const homedir = options.homedir ?? os.homedir;
+  const stateDir = env.OPENCLAW_STATE_DIR?.trim()
+    ? expandUserPath(env.OPENCLAW_STATE_DIR, env, homedir)
+    : path.join(resolveHomeDir(env, homedir), ".openclaw");
+  return path.join(stateDir, "skills");
+}
+
+export function resolveDefaultGlobalSkillsRoot(options = {}) {
+  const env = options.env ?? process.env;
+  const homedir = options.homedir ?? os.homedir;
+
+  if (env.AGENTS_SKILLS_DIR?.trim()) {
+    return expandUserPath(env.AGENTS_SKILLS_DIR, env, homedir);
+  }
+
+  if (env.AGENTS_HOME?.trim()) {
+    return path.join(expandUserPath(env.AGENTS_HOME, env, homedir), "skills");
+  }
+
+  return path.join(resolveHomeDir(env, homedir), ".agents", "skills");
+}
+
+export function resolveInstallRoots(options = {}) {
+  if (options.destRoot) {
+    return [expandUserPath(options.destRoot, options.env, options.homedir)];
+  }
+
+  const roots = [
+    resolveDefaultSkillsRoot(options),
+    resolveDefaultGlobalSkillsRoot(options)
+  ];
+
+  return [...new Set(roots.map((root) => path.resolve(root)))];
+}
+
+export async function pathExists(targetPath) {
+  try {
+    await fs.access(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function randomSuffix() {
+  return `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}
+
+async function copyDirectoryAtomic({ sourceDir, finalDir, replaceExisting }) {
+  const destinationRoot = path.dirname(finalDir);
+  const destinationName = path.basename(finalDir);
+
+  await fs.mkdir(destinationRoot, { recursive: true });
+
+  const tmpRoot = await fs.mkdtemp(path.join(destinationRoot, `.tmp-${destinationName}-`));
+  const stagedDir = path.join(tmpRoot, destinationName);
+  let backupDir = null;
+
+  try {
+    await fs.cp(sourceDir, stagedDir, {
+      recursive: true,
+      force: false,
+      errorOnExist: true
+    });
+
+    const destinationExists = await pathExists(finalDir);
+    if (destinationExists) {
+      if (!replaceExisting) {
+        throw new Error(`Destination already exists: ${finalDir}. Re-run with --force to replace it.`);
+      }
+
+      backupDir = path.join(destinationRoot, `.${destinationName}.backup-${randomSuffix()}`);
+      await fs.rename(finalDir, backupDir);
+    }
+
+    await fs.rename(stagedDir, finalDir);
+
+    if (backupDir) {
+      await fs.rm(backupDir, { recursive: true, force: true });
+      backupDir = null;
+    }
+  } catch (error) {
+    if (backupDir && !(await pathExists(finalDir)) && (await pathExists(backupDir))) {
+      await fs.rename(backupDir, finalDir).catch(() => undefined);
+    }
+    throw error;
+  } finally {
+    await fs.rm(tmpRoot, { recursive: true, force: true }).catch(() => undefined);
+  }
+}
+
+export async function installSkills(options) {
+  const env = options.env ?? process.env;
+  const homedir = options.homedir ?? os.homedir;
+  const packageRoot = options.packageRoot ?? resolvePackageRoot(import.meta.url);
+  const replaceExisting = options.replaceExisting ?? true;
+  const dryRun = Boolean(options.dryRun);
+  const destinationRoots = resolveInstallRoots({
+    destRoot: options.destRoot,
+    env,
+    homedir
+  });
+
+  const targets = resolveInstallTargets(options.requested);
+  const installed = [];
+
+  for (const target of targets) {
+    const sourceDir = path.join(packageRoot, "skills", target.packageDir);
+
+    if (!(await pathExists(sourceDir))) {
+      throw new Error(`Missing packaged skill source: ${sourceDir}`);
+    }
+
+    for (const destinationRoot of destinationRoots) {
+      const finalDir = path.join(destinationRoot, target.packageDir);
+
+      if (!dryRun) {
+        await copyDirectoryAtomic({ sourceDir, finalDir, replaceExisting });
+      }
+
+      installed.push({
+        key: target.key,
+        skillName: target.skillName,
+        sourceDir,
+        finalDir,
+        destinationRoot
+      });
+    }
+  }
+
+  return {
+    destinationRoots,
+    dryRun,
+    replaceExisting,
+    installed
+  };
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@axon-chain/axon-skills",
+  "version": "0.1.0",
+  "description": "OpenClaw-installable Axon mainnet skills for validator operators and ordinary users.",
+  "type": "module",
+  "bin": {
+    "axon-skills": "./bin/axon-skills.js"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "skills"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "axon",
+    "openclaw",
+    "skills",
+    "validator",
+    "wallet"
+  ],
+  "license": "Apache-2.0"
+}

package/skills/axon-mainnet-user/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: axon-mainnet-user
+description: Help ordinary users connect a wallet to Axon mainnet, check balances, inspect the chain through the public RPC, and send basic transactions. Use for MetaMask setup, AXON balance checks, public JSON-RPC reads, and wallet troubleshooting. Do not use for validator, SDK, or contract-deployment workflows.
+metadata: {"openclaw":{"skillKey":"axon-mainnet-user","emoji":"🧭"}}
+---
+
+# Axon Mainnet User
+
+Use this skill when the user is an ordinary Axon mainnet participant who needs wallet-first help.
+
+Do not use this skill for validator nodes, sync nodes, SDK integration, or contract deployment. If the user wants to run a node or become a validator, switch to `axon-validator-node`.
+
+## Non-negotiable rules
+
+- Wallet-facing chain ID is `8210`.
+- Public RPC is `https://mainnet-rpc.axonchain.ai/`.
+- `AXON` is the gas token.
+- `axon_8210-1` is the Cosmos node chain ID and should not be used as the MetaMask chain ID.
+- Keep this skill wallet-first. Do not turn it into a validator workflow.
+
+## Workflow routing
+
+- For wallet onboarding and network fields, read `references/mainnet-wallet.md`.
+- For direct public JSON-RPC reads, read `references/basic-rpc-usage.md`.
+- For wrong-network, gas, or RPC errors, read `references/user-troubleshooting.md`.
+
+## Response policy
+
+- Give wallet configuration steps and public RPC examples.
+- Prefer public RPC checks over node-operator commands.
+- Keep advanced builder or validator topics out of scope in v1.
+- If the user drifts into node operation, redirect to `axon-validator-node`.

package/skills/axon-mainnet-user/references/basic-rpc-usage.md

@@ -0,0 +1,48 @@
+# Basic Public JSON-RPC Usage
+
+Use the public endpoint:
+
+- `https://mainnet-rpc.axonchain.ai/`
+
+## Read the wallet-facing chain ID
+
+```bash
+curl -s https://mainnet-rpc.axonchain.ai/ \
+  -H 'content-type: application/json' \
+  --data '{"jsonrpc":"2.0","method":"eth_chainId","params":[],"id":1}'
+```
+
+Expected result:
+
+- `0x2012`, which is decimal `8210`
+
+## Read the latest block number
+
+```bash
+curl -s https://mainnet-rpc.axonchain.ai/ \
+  -H 'content-type: application/json' \
+  --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'
+```
+
+## Read an address balance
+
+Replace `<EVM_ADDRESS>` with a `0x...` address:
+
+```bash
+curl -s https://mainnet-rpc.axonchain.ai/ \
+  -H 'content-type: application/json' \
+  --data '{"jsonrpc":"2.0","method":"eth_getBalance","params":["<EVM_ADDRESS>","latest"],"id":1}'
+```
+
+The balance is returned in hex wei-style units for the EVM side.
+
+## When to stop and redirect
+
+If the user asks for:
+
+- validator registration
+- node sync
+- P2P bootstrap
+- the validator registration transaction
+
+Switch to `axon-validator-node`.

package/skills/axon-mainnet-user/references/mainnet-wallet.md

@@ -0,0 +1,34 @@
+# Axon Mainnet Wallet Setup
+
+## MetaMask network fields
+
+- Network name: `Axon`
+- RPC URL: `https://mainnet-rpc.axonchain.ai/`
+- Chain ID: `8210`
+- Currency symbol: `AXON`
+
+## Important distinction
+
+- Use `8210` in MetaMask and other EVM wallets.
+- `axon_8210-1` is for Cosmos node operators, not wallet setup.
+
+## What users can do with this setup
+
+- view AXON balances
+- send AXON transfers
+- connect EVM dapps that support Axon mainnet
+- inspect chain state through the public RPC
+
+## Before sending transactions
+
+- confirm the wallet is on chain ID `8210`
+- confirm the wallet has enough AXON for gas
+- confirm the recipient address format matches the tool being used
+
+## Public RPC
+
+Use only:
+
+- `https://mainnet-rpc.axonchain.ai/`
+
+Do not send ordinary wallet users to validator bootstrap peers or node-only chain IDs.

package/skills/axon-mainnet-user/references/user-troubleshooting.md

@@ -0,0 +1,61 @@
+# User Troubleshooting
+
+## Wrong network in wallet
+
+Symptoms:
+
+- transactions fail immediately
+- wallet shows a different chain
+- dapp requests a chain switch
+
+Fix:
+
+- set MetaMask chain ID to `8210`
+- keep RPC URL at `https://mainnet-rpc.axonchain.ai/`
+- do not use `axon_8210-1` in wallet configuration
+
+## No gas for a transaction
+
+Symptoms:
+
+- wallet says insufficient funds
+- transfer cannot be signed or broadcast
+
+Fix:
+
+- fund the wallet with `AXON`
+- leave some AXON unspent for gas
+
+## Public RPC seems unavailable
+
+Checks:
+
+```bash
+curl -s https://mainnet-rpc.axonchain.ai/ \
+  -H 'content-type: application/json' \
+  --data '{"jsonrpc":"2.0","method":"eth_chainId","params":[],"id":1}'
+```
+
+If this fails:
+
+- retry later
+- confirm the wallet or app is still pointed at the public Axon RPC
+- avoid switching the user into validator-only node endpoints
+
+## Chain ID confusion
+
+- `8210` is the EVM wallet chain ID
+- `axon_8210-1` is the Cosmos node chain ID
+
+Correct the configuration before moving on.
+
+## Out-of-scope requests
+
+If the user asks to:
+
+- run a validator
+- bootstrap a node
+- troubleshoot peers
+- submit the validator registration transaction
+
+Switch to `axon-validator-node`.

package/skills/axon-validator-node/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: axon-validator-node
+description: Help users bootstrap, fund, sync, create, verify, and operate an Axon mainnet validator with the official script-based workflow. Use for validator onboarding, sync checks, create-validator troubleshooting, fee issues, peer issues, key handling, and ongoing node operations.
+metadata: {"openclaw":{"skillKey":"axon-validator-node","emoji":"⛓️"}}
+---
+
+# Axon Validator Node
+
+Use this skill when the user wants to run, recover, verify, or troubleshoot an Axon mainnet validator or sync node.
+
+Do not use this skill for ordinary wallet usage. If the user only needs MetaMask, balances, transfers, or public RPC reads, switch to `axon-mainnet-user`.
+
+## Non-negotiable rules
+
+- Mainnet node identity uses Cosmos chain ID `axon_8210-1`.
+- Wallet-facing EVM tooling uses chain ID `8210`.
+- Prefer the official script workflow from the `axon-chain/axon` repository.
+- Do not suggest a manual `axond init` plus manual genesis-fetch flow unless the user explicitly needs low-level debugging.
+- Do not tell the user to submit `create-validator` until the validator account is funded, local RPC is up, and `catching_up` is `false`.
+- Treat the mnemonic, `KEYRING_PASSWORD_FILE`, validator key files, and any signing key material as sensitive.
+- Current practical transaction default: use `GAS_PRICES=1000000000aaxon` unless the local helper already sets a non-zero gas price.
+
+## Workflow routing
+
+- For first-time setup, rebuilds, or exact shell commands, read `references/mainnet-validator.md`.
+- For backups, exposed ports, double-sign prevention, and key hygiene, read `references/validator-security.md`.
+- For fee failures, peer failures, sync lag, or missing validator status, read `references/validator-troubleshooting.md`.
+
+## Response policy
+
+- Give exact commands when operating the node.
+- Keep `axon_8210-1` and `8210` clearly separated in the response.
+- Prefer `start_validator_node.sh` and `start_sync_node.sh` over lower-level alternatives.
+- If the user asks to proceed with `create-validator`, explicitly check sync state, funding state, and local RPC readiness first.

package/skills/axon-validator-node/references/mainnet-validator.md

@@ -0,0 +1,149 @@
+# Axon Mainnet Validator Workflow
+
+## Network constants
+
+- Cosmos chain ID: `axon_8210-1`
+- EVM chain ID: `8210`
+- Public wallet RPC: `https://mainnet-rpc.axonchain.ai/`
+- Bootstrap peer: `e47ec82a1d08a371e3c235e6554496be2f114eae@mainnet-node.axonchain.ai:26656`
+- Genesis file: `https://raw.githubusercontent.com/axon-chain/axon/main/docs/mainnet/genesis.json`
+- Bootstrap peers file: `https://raw.githubusercontent.com/axon-chain/axon/main/docs/mainnet/bootstrap_peers.txt`
+
+## Preferred working directory
+
+Use `/opt/axon-node` for bare metal and containerized installs.
+
+## Bootstrap the validator workspace
+
+```bash
+mkdir -p /opt/axon-node
+cd /opt/axon-node
+
+curl -fsSLo start_validator_node.sh https://raw.githubusercontent.com/axon-chain/axon/main/scripts/start_validator_node.sh
+curl -fsSLo start_sync_node.sh https://raw.githubusercontent.com/axon-chain/axon/main/scripts/start_sync_node.sh
+curl -fsSLo genesis.json https://raw.githubusercontent.com/axon-chain/axon/main/docs/mainnet/genesis.json
+curl -fsSLo bootstrap_peers.txt https://raw.githubusercontent.com/axon-chain/axon/main/docs/mainnet/bootstrap_peers.txt
+chmod 0755 start_validator_node.sh start_sync_node.sh
+printf 'replace-with-a-strong-passphrase\n' > keyring.pass
+chmod 0600 keyring.pass
+```
+
+## Optional: pre-download `axond`
+
+For Linux AMD64:
+
+```bash
+curl -fsSLo axond https://github.com/axon-chain/axon/releases/latest/download/axond_linux_amd64
+curl -fsSLo axond.sha256 https://github.com/axon-chain/axon/releases/latest/download/axond_linux_amd64.sha256
+echo "$(cat axond.sha256)  axond" | sha256sum -c -
+chmod 0755 axond
+```
+
+Adjust the release asset URL for a different platform if needed.
+
+## Initialize the validator account
+
+```bash
+cd /opt/axon-node
+KEYRING_PASSWORD_FILE=/opt/axon-node/keyring.pass ./start_validator_node.sh init
+```
+
+What this creates:
+
+- `data/validator.address`
+- `data/validator.valoper`
+- `data/validator.consensus_pubkey.json`
+- `data/peer_info.txt`
+
+The mnemonic is only printed once when a new account is generated.
+
+## Start the node
+
+```bash
+cd /opt/axon-node
+KEYRING_PASSWORD_FILE=/opt/axon-node/keyring.pass ./start_validator_node.sh start
+```
+
+Default ports:
+
+- P2P: `26656`
+- CometBFT RPC: `26657`
+- JSON-RPC: `8545`
+- JSON-RPC WS: `8546`
+- REST API: `1317`
+- gRPC: `9090`
+
+## Verify sync before any validator transaction
+
+```bash
+curl -s http://127.0.0.1:26657/status | jq '.result.sync_info'
+```
+
+Wait until:
+
+- latest block height is moving
+- peer count is non-zero
+- `catching_up` becomes `false`
+
+Do not submit `create-validator` before `catching_up=false`.
+
+## Fund the validator account
+
+Read the address from `data/validator.address` and transfer AXON to it.
+
+Example:
+
+```bash
+cat /opt/axon-node/data/validator.address
+```
+
+## Submit `create-validator`
+
+Use a non-zero gas price. Current safe default:
+
+- `GAS_PRICES=1000000000aaxon`
+
+Command:
+
+```bash
+cd /opt/axon-node
+KEYRING_PASSWORD_FILE=/opt/axon-node/keyring.pass \
+COMETBFT_RPC=http://127.0.0.1:26657 \
+GAS_PRICES=1000000000aaxon \
+./start_validator_node.sh create-validator
+```
+
+Notes:
+
+- The official script default self-bond is `100 AXON` unless `VALIDATOR_STAKE` is overridden.
+- The node must already be running locally when you point `COMETBFT_RPC` at `http://127.0.0.1:26657`.
+
+## Verify validator status
+
+Query the transaction if needed:
+
+```bash
+curl -s http://127.0.0.1:1317/cosmos/tx/v1beta1/txs/<TX_HASH>
+```
+
+Query the validator:
+
+```bash
+axond query staking validator "$(cat /opt/axon-node/data/validator.valoper)" \
+  --node http://127.0.0.1:26657 \
+  --output json
+```
+
+Useful success indicators:
+
+- validator exists on chain
+- validator has tokens bonded
+- status is `BOND_STATUS_BONDED` or the expected waiting-state for the network
+
+## Ongoing operations
+
+- Logs: `tail -f /opt/axon-node/data/node.log`
+- Sync info: `curl -s http://127.0.0.1:26657/status | jq '.result.sync_info'`
+- Validator address: `cat /opt/axon-node/data/validator.valoper`
+- Bootstrap peers should stay aligned with the official repository
+- Set `P2P_EXTERNAL_ADDRESS=host:26656` only on a public inbound validator

package/skills/axon-validator-node/references/validator-security.md

@@ -0,0 +1,50 @@
+# Validator Security
+
+## Sensitive material
+
+Treat these as secrets:
+
+- mnemonic
+- `keyring.pass`
+- `data/node/config/priv_validator_key.json`
+- any imported mnemonic source file
+
+Do not paste them into chat, public issues, or shared docs.
+
+## Backups
+
+Back up at least:
+
+- `/opt/axon-node/keyring.pass`
+- `/opt/axon-node/data/validator.address`
+- `/opt/axon-node/data/validator.valoper`
+- `/opt/axon-node/data/node/config/priv_validator_key.json`
+- the mnemonic if the validator account was generated locally
+
+Keep backups offline when possible.
+
+## Double-sign prevention
+
+- Never run the same validator signing key on two live machines at the same time.
+- If moving the validator, stop the old node completely before starting the new one.
+- Treat failover automation as high risk unless the handoff is explicit and verified.
+
+## RPC and network exposure
+
+- Leave `P2P_EXTERNAL_ADDRESS` unset on ordinary outbound-only nodes.
+- Only expose `26656` when the node should accept inbound peers.
+- Keep admin access to the host locked down.
+- Do not expose key material over network shares.
+
+## Operational hygiene
+
+- Use a dedicated machine or VM for validator duties.
+- Keep system time correct and disks healthy.
+- Monitor logs for downtime and peer churn.
+- Review upgrade notes before restarting production validators.
+
+## Chain ID hygiene
+
+- Use `axon_8210-1` for node commands and validator operations.
+- Use `8210` for wallet-facing EVM tools only.
+- Do not mix them.

package/skills/axon-validator-node/references/validator-troubleshooting.md

@@ -0,0 +1,95 @@
+# Validator Troubleshooting
+
+## `fee not provided` or `insufficient fee`
+
+Symptom:
+
+- `create-validator` returns `fee not provided`
+- raw log mentions insufficient fee
+
+Fix:
+
+```bash
+cd /opt/axon-node
+KEYRING_PASSWORD_FILE=/opt/axon-node/keyring.pass \
+COMETBFT_RPC=http://127.0.0.1:26657 \
+GAS_PRICES=1000000000aaxon \
+./start_validator_node.sh create-validator
+```
+
+Use a non-zero gas price until the local helper script already defaults to one.
+
+## `catching_up` stays `true`
+
+Checks:
+
+```bash
+curl -s http://127.0.0.1:26657/status | jq '.result.sync_info'
+cat /opt/axon-node/data/peer_info.txt
+tail -f /opt/axon-node/data/node.log
+```
+
+Actions:
+
+- confirm the bootstrap peers file matches the official repository
+- confirm the node has reachable peers
+- confirm disk and network are not constrained
+- wait before any validator transaction
+
+Do not submit `create-validator` until `catching_up=false`.
+
+## Missing `KEYRING_PASSWORD_FILE`
+
+Symptoms:
+
+- the script refuses to run
+- the keyring password file is missing or empty
+
+Fix:
+
+```bash
+ls -l /opt/axon-node/keyring.pass
+cat /opt/axon-node/keyring.pass
+chmod 0600 /opt/axon-node/keyring.pass
+```
+
+Use a non-empty local passphrase file and point `KEYRING_PASSWORD_FILE` at it.
+
+## Validator not found after submission
+
+Checks:
+
+```bash
+curl -s http://127.0.0.1:1317/cosmos/tx/v1beta1/txs/<TX_HASH>
+axond query staking validator "$(cat /opt/axon-node/data/validator.valoper)" \
+  --node http://127.0.0.1:26657 \
+  --output json
+```
+
+Possible causes:
+
+- the transaction never landed
+- the validator transaction was rejected
+- the wrong RPC endpoint was queried
+
+## No peers or unstable peers
+
+Checks:
+
+```bash
+tail -f /opt/axon-node/data/node.log
+cat /opt/axon-node/bootstrap_peers.txt
+```
+
+Actions:
+
+- re-sync the official bootstrap peers file
+- verify outbound connectivity to `mainnet-node.axonchain.ai:26656`
+- only set `P2P_EXTERNAL_ADDRESS` when the host is publicly reachable
+
+## Chain ID confusion
+
+- `axon_8210-1` is the Cosmos chain ID for validator and node commands
+- `8210` is the EVM chain ID for wallets
+
+If the user mixes them, correct the command before continuing.