@jellylegsai/aether-cli 1.8.0

package/lib/errors.js

@@ -0,0 +1,398 @@
+/**
+ * aether-cli lib/errors.js
+ * 
+ * Centralized error handling for production-grade CLI experience.
+ * Provides consistent error formatting, retry logic, and user-friendly messages.
+ */
+
+// ANSI colours
+const C = {
+  reset: '\x1b[0m',
+  bright: '\x1b[1m',
+  dim: '\x1b[2m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  cyan: '\x1b[36m',
+  magenta: '\x1b[35m',
+};
+
+/**
+ * Error categories for user-friendly messaging
+ */
+const ERROR_CATEGORIES = {
+  NETWORK: 'network',
+  RPC: 'rpc',
+  VALIDATION: 'validation',
+  CONFIG: 'config',
+  WALLET: 'wallet',
+  PERMISSION: 'permission',
+  TIMEOUT: 'timeout',
+  UNKNOWN: 'unknown',
+};
+
+/**
+ * User-friendly error messages by category
+ */
+const ERROR_MESSAGES = {
+  [ERROR_CATEGORIES.NETWORK]: {
+    title: 'Network Error',
+    description: 'Unable to reach the Aether network.',
+    suggestions: [
+      'Check your internet connection',
+      'Verify the RPC endpoint is accessible',
+      'Try using --rpc to specify a different endpoint',
+    ],
+  },
+  [ERROR_CATEGORIES.RPC]: {
+    title: 'RPC Error',
+    description: 'The Aether node returned an error.',
+    suggestions: [
+      'The node may be syncing - try again in a few moments',
+      'Check if the RPC endpoint is correct',
+      'Try a different RPC endpoint with --rpc <url>',
+    ],
+  },
+  [ERROR_CATEGORIES.VALIDATION]: {
+    title: 'Validation Error',
+    description: 'Invalid input provided.',
+    suggestions: [
+      'Check the command syntax with --help',
+      'Verify addresses are valid base58 format',
+      'Ensure amounts are positive numbers',
+    ],
+  },
+  [ERROR_CATEGORIES.CONFIG]: {
+    title: 'Configuration Error',
+    description: 'CLI configuration issue detected.',
+    suggestions: [
+      'Run "aether config init" to create default config',
+      'Check ~/.aether/config.json exists and is valid JSON',
+      'Use "aether config validate" to check settings',
+    ],
+  },
+  [ERROR_CATEGORIES.WALLET]: {
+    title: 'Wallet Error',
+    description: 'Unable to access wallet.',
+    suggestions: [
+      'Ensure you have created a wallet: aether wallet create',
+      'Check the wallet address is correct',
+      'Verify wallet files exist in ~/.aether/wallets/',
+    ],
+  },
+  [ERROR_CATEGORIES.PERMISSION]: {
+    title: 'Permission Error',
+    description: 'Insufficient permissions.',
+    suggestions: [
+      'Check file permissions in ~/.aether/',
+      'Ensure you own the wallet files',
+      'Try running with appropriate privileges',
+    ],
+  },
+  [ERROR_CATEGORIES.TIMEOUT]: {
+    title: 'Request Timeout',
+    description: 'The request took too long to complete.',
+    suggestions: [
+      'The network may be congested - try again',
+      'Increase timeout with AETHER_RPC_TIMEOUT env var',
+      'Check if the RPC endpoint is responsive',
+    ],
+  },
+  [ERROR_CATEGORIES.UNKNOWN]: {
+    title: 'Unexpected Error',
+    description: 'An unexpected error occurred.',
+    suggestions: [
+      'Try the command again',
+      'Check logs with --verbose flag',
+      'Report this issue with the error details',
+    ],
+  },
+};
+
+/**
+ * Categorize an error based on its properties
+ */
+function categorizeError(error) {
+  if (!error) return ERROR_CATEGORIES.UNKNOWN;
+  
+  const message = (error.message || '').toLowerCase();
+  const code = error.code || '';
+  
+  // Network errors
+  if (message.includes('enetunreach') || 
+      message.includes('econnrefused') ||
+      message.includes('econnreset') ||
+      message.includes('socket') ||
+      message.includes('network') ||
+      code === 'ECONNREFUSED' ||
+      code === 'ENOTFOUND' ||
+      code === 'ENETUNREACH') {
+    return ERROR_CATEGORIES.NETWORK;
+  }
+  
+  // RPC errors
+  if (message.includes('rpc') ||
+      message.includes('json-rpc') ||
+      message.includes('-32000') ||
+      message.includes('method not found') ||
+      message.includes('invalid params') ||
+      error.statusCode >= 500) {
+    return ERROR_CATEGORIES.RPC;
+  }
+  
+  // Validation errors
+  if (message.includes('invalid') ||
+      message.includes('required') ||
+      message.includes('must be') ||
+      message.includes('cannot be') ||
+      message.includes('bad request') ||
+      error.statusCode === 400) {
+    return ERROR_CATEGORIES.VALIDATION;
+  }
+  
+  // Config errors
+  if (message.includes('config') ||
+      message.includes('enoent') && message.includes('config')) {
+    return ERROR_CATEGORIES.CONFIG;
+  }
+  
+  // Wallet errors
+  if (message.includes('wallet') ||
+      message.includes('keypair') ||
+      message.includes('mnemonic') ||
+      message.includes('signature')) {
+    return ERROR_CATEGORIES.WALLET;
+  }
+  
+  // Permission errors
+  if (message.includes('eperm') ||
+      message.includes('eacces') ||
+      code === 'EACCES' ||
+      code === 'EPERM') {
+    return ERROR_CATEGORIES.PERMISSION;
+  }
+  
+  // Timeout errors
+  if (message.includes('timeout') ||
+      message.includes('etimedout') ||
+      code === 'ETIMEDOUT') {
+    return ERROR_CATEGORIES.TIMEOUT;
+  }
+  
+  return ERROR_CATEGORIES.UNKNOWN;
+}
+
+/**
+ * Format error for display
+ */
+function formatError(error, options = {}) {
+  const { verbose = false, exit = true } = options;
+  const category = categorizeError(error);
+  const template = ERROR_MESSAGES[category];
+  
+  let output = '\n';
+  output += `${C.red}${C.bright}✖ ${template.title}${C.reset}\n`;
+  output += `${C.dim}${template.description}${C.reset}\n\n`;
+  
+  if (error.message) {
+    output += `${C.yellow}Error: ${error.message}${C.reset}\n`;
+  }
+  
+  if (verbose && error.stack) {
+    output += `\n${C.dim}Stack trace:${C.reset}\n`;
+    output += `${C.dim}${error.stack}${C.reset}\n`;
+  }
+  
+  output += `\n${C.bright}Suggestions:${C.reset}\n`;
+  template.suggestions.forEach(suggestion => {
+    output += `  ${C.cyan}•${C.reset} ${suggestion}\n`;
+  });
+  
+  return output;
+}
+
+/**
+ * Display error and optionally exit
+ */
+function displayError(error, options = {}) {
+  const { exit = true, exitCode = 1, verbose = process.env.AETHER_VERBOSE === '1' } = options;
+  
+  console.error(formatError(error, { verbose }));
+  
+  if (exit) {
+    process.exit(exitCode);
+  }
+}
+
+/**
+ * Wrap an async function with error handling
+ */
+function withErrorHandling(fn, options = {}) {
+  return async function(...args) {
+    try {
+      return await fn(...args);
+    } catch (error) {
+      displayError(error, options);
+      return null;
+    }
+  };
+}
+
+/**
+ * Retry an async operation with exponential backoff
+ */
+async function withRetry(operation, options = {}) {
+  const {
+    maxRetries = 3,
+    initialDelay = 1000,
+    maxDelay = 30000,
+    backoffMultiplier = 2,
+    retryableErrors = null, // null = retry all
+    onRetry = null,
+  } = options;
+  
+  let lastError;
+  let delay = initialDelay;
+  
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      return await operation();
+    } catch (error) {
+      lastError = error;
+      
+      // Check if we should retry this error
+      if (retryableErrors && !retryableErrors.some(e => error instanceof e)) {
+        throw error;
+      }
+      
+      // Don't retry on validation errors
+      const category = categorizeError(error);
+      if (category === ERROR_CATEGORIES.VALIDATION) {
+        throw error;
+      }
+      
+      if (attempt < maxRetries) {
+        if (onRetry) {
+          onRetry(error, attempt + 1, maxRetries);
+        }
+        
+        await sleep(delay);
+        delay = Math.min(delay * backoffMultiplier, maxDelay);
+      }
+    }
+  }
+  
+  throw lastError;
+}
+
+/**
+ * Sleep utility
+ */
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+/**
+ * Create a RPC call wrapper with retry logic
+ */
+function createRpcCaller(clientMethod, options = {}) {
+  return async function(...args) {
+    return withRetry(
+      () => clientMethod(...args),
+      {
+        maxRetries: 3,
+        initialDelay: 1000,
+        onRetry: (error, attempt, max) => {
+          console.log(
+            `${C.yellow}⚠ RPC call failed (attempt ${attempt}/${max}): ${error.message}${C.reset}`
+          );
+        },
+        ...options,
+      }
+    );
+  };
+}
+
+/**
+ * Validate required arguments
+ */
+function validateRequired(args, requirements) {
+  const missing = [];
+  
+  for (const requirement of requirements) {
+    if (requirement.validator ? !requirement.validator(args) : !args[requirement.name]) {
+      missing.push(requirement.displayName || requirement.name);
+    }
+  }
+  
+  if (missing.length > 0) {
+    const error = new Error(`Missing required arguments: ${missing.join(', ')}`);
+    error.isValidationError = true;
+    throw error;
+  }
+}
+
+/**
+ * Validate address format (base58)
+ */
+function validateAddress(address, fieldName = 'address') {
+  if (!address) {
+    throw new Error(`${fieldName} is required`);
+  }
+  
+  // Base58 regex (simplified)
+  const base58Regex = /^[1-9A-HJ-NP-Za-km-z]+$/;
+  if (!base58Regex.test(address)) {
+    throw new Error(`Invalid ${fieldName} format: must be base58 encoded`);
+  }
+  
+  // Typical Solana/Aether addresses are 32-44 chars
+  if (address.length < 32 || address.length > 44) {
+    throw new Error(`Invalid ${fieldName} length: expected 32-44 characters, got ${address.length}`);
+  }
+  
+  return true;
+}
+
+/**
+ * Validate amount (positive number)
+ */
+function validateAmount(amount, fieldName = 'amount') {
+  if (amount === undefined || amount === null || amount === '') {
+    throw new Error(`${fieldName} is required`);
+  }
+  
+  const num = Number(amount);
+  if (isNaN(num) || !isFinite(num)) {
+    throw new Error(`Invalid ${fieldName}: must be a valid number`);
+  }
+  
+  if (num <= 0) {
+    throw new Error(`Invalid ${fieldName}: must be greater than 0`);
+  }
+  
+  return num;
+}
+
+module.exports = {
+  // Constants
+  ERROR_CATEGORIES,
+  ERROR_MESSAGES,
+  
+  // Core functions
+  categorizeError,
+  formatError,
+  displayError,
+  withErrorHandling,
+  withRetry,
+  createRpcCaller,
+  
+  // Validation
+  validateRequired,
+  validateAddress,
+  validateAmount,
+  
+  // Utilities
+  sleep,
+  C,
+};

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@jellylegsai/aether-cli",
+  "version": "1.8.0",
+  "description": "Aether CLI - Validator Onboarding, Staking, and Blockchain Operations",
+  "main": "index.js",
+  "bin": {
+    "aether-cli": "./index.js",
+    "aether": "./index.js"
+  },
+  "scripts": {
+    "test": "node test.js && cd sdk && node test.js",
+    "lint": "echo 'No linting configured'",
+    "doctor": "node index.js doctor",
+    "init": "node index.js init",
+    "monitor": "node index.js monitor",
+    "logs": "node index.js logs",
+    "sdk": "node index.js sdk",
+    "sdk-test": "node index.js sdk-test",
+    "wallet": "node index.js wallet",
+    "stake": "node index.js stake",
+    "stake-positions": "node index.js stake-positions",
+    "unstake": "node index.js unstake",
+    "claim": "node index.js claim",
+    "delegations": "node index.js delegations",
+    "rewards": "node index.js rewards",
+    "validators": "node index.js validators",
+    "validator": "node index.js validator",
+    "validator-register": "node index.js validator-register",
+    "validator-start": "node index.js validator-start",
+    "validator-status": "node index.js validator-status",
+    "validator-info": "node index.js validator-info",
+    "multisig": "node index.js multisig",
+    "transfer": "node index.js transfer",
+    "balance": "node index.js balance",
+    "tx-history": "node index.js tx-history",
+    "tx": "node index.js tx-history",
+    "network": "node index.js network",
+    "epoch": "node index.js epoch",
+    "supply": "node index.js supply",
+    "status": "node index.js status",
+    "blockhash": "node index.js blockhash",
+    "tps": "node index.js tps",
+    "fees": "node index.js fees",
+    "apy": "node index.js apy",
+    "account": "node index.js account",
+    "price": "node index.js price",
+    "emergency": "node index.js emergency",
+    "snapshot": "node index.js snapshot",
+    "nft": "node index.js nft",
+    "prepare-publish": "npm pack && echo 'Package ready for publishing'",
+    "version-bump": "node -e \"const fs=require('fs');let p=JSON.parse(fs.readFileSync('package.json'));let v=p.version.split('.');v[2]=parseInt(v[2])+1;p.version=v.join('.');fs.writeFileSync('package.json',JSON.stringify(p,null,2));console.log('Version bumped to',p.version);\""
+  },
+  "keywords": [
+    "aether",
+    "blockchain",
+    "validator",
+    "staking",
+    "cryptocurrency",
+    "multi-signature",
+    "cli"
+  ],
+  "author": "Jelly-legs AI Team",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jelly-legs-ai/Jelly-legs-unsteady-workshop"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "dependencies": {
+    "bip39": "^3.0.4",
+    "tweetnacl": "^1.0.3",
+    "bs58": "^5.0.0"
+  }
+}

package/sdk/README.md

@@ -0,0 +1,210 @@
+# @jellylegsai/aether-sdk
+
+Official Aether Blockchain SDK for Node.js. Every function makes **REAL HTTP RPC calls** to the Aether blockchain at `http://127.0.0.1:8899`. No stubs, no mocks.
+
+## Installation
+
+```bash
+npm install @jellylegsai/aether-sdk
+```
+
+Or use locally from the `sdk/` folder in this repo:
+
+```javascript
+const aether = require('./sdk');
+```
+
+## Quick Start
+
+```javascript
+const aether = require('@jellylegsai/aether-sdk');
+
+// Get current slot
+const slot = await aether.getSlot();
+console.log('Current slot:', slot);
+
+// Get account balance
+const balance = await aether.getBalance('ATH...');
+console.log('Balance:', balance);
+
+// Use custom RPC endpoint
+const client = new aether.AetherClient({ rpcUrl: 'http://127.0.0.1:8899' });
+const epoch = await client.getEpochInfo();
+```
+
+## SDK Architecture
+
+- **`AetherClient`** — Full-featured blockchain client class. All methods make real HTTP calls.
+- **Convenience functions** — Top-level exports for one-off queries using the default RPC.
+- **Low-level RPC helpers** — `rpcGet` / `rpcPost` for custom requests.
+
+Default RPC: `http://127.0.0.1:8899` (override via `AETHER_RPC` env or constructor option).
+
+## AetherClient
+
+```javascript
+const aether = require('@jellylegsai/aether-sdk');
+
+const client = new aether.AetherClient({
+  rpcUrl: 'http://127.0.0.1:8899',  // default
+  timeoutMs: 10000,                  // default: 10s
+});
+```
+
+## API Reference
+
+### Chain Queries
+
+| Method | Returns | RPC Endpoint |
+|--------|---------|--------------|
+| `getSlot()` | `number` — current slot | `GET /v1/slot` |
+| `getBlockHeight()` | `number` — block height | `GET /v1/blockheight` |
+| `getEpochInfo()` | `object` — epoch + slot info | `GET /v1/epoch` |
+| `getAccountInfo(address)` | `object` — lamports, owner, data | `GET /v1/account/:address` |
+| `getBalance(address)` | `number` — lamports | `GET /v1/account/:address` |
+| `getTransaction(signature)` | `object` — tx details | `GET /v1/transaction/:sig` |
+| `getRecentTransactions(address, limit?)` | `array` — recent txs | `GET /v1/transactions/:address` |
+| `getTokenAccounts(address)` | `array` — SPL token accounts | `GET /v1/tokens/:address` |
+| `getStakeAccounts(address)` | `array` — stake accounts | `GET /v1/stake-accounts/:address` |
+| `getStakePositions(address)` | `array` — delegations | `GET /v1/stake/:address` |
+| `getRewards(address)` | `object` — staking rewards | `GET /v1/rewards/:address` |
+| `getValidators()` | `array` — validator list | `GET /v1/validators` |
+| `getValidatorAPY(validatorAddr)` | `object` — APY data | `GET /v1/validator/:addr/apy` |
+| `getTPS()` | `number` — TPS | `GET /v1/tps` |
+| `getSupply()` | `object` — total/circulating/non-circulating | `GET /v1/supply` |
+| `getFees()` | `object` — fee estimates | `GET /v1/fees` |
+| `getSlotProduction()` | `object` — slot production | `POST /v1/slot_production` |
+| `getClusterPeers()` | `array` — peer list | `GET /v1/peers` |
+| `getHealth()` | `string` — "ok" if healthy | `GET /v1/health` |
+| `getVersion()` | `object` — node version | `GET /v1/version` |
+
+### Blockhash (required for signing)
+
+| Method | Returns | RPC Endpoint |
+|--------|---------|--------------|
+| `getRecentBlockhash()` | `{ blockhash, lastValidBlockHeight }` | `GET /v1/recent-blockhash` |
+
+### Transaction Submission
+
+| Method | Returns | RPC Endpoint |
+|--------|---------|--------------|
+| `sendTransaction(tx)` | `object` — receipt | `POST /v1/transaction` |
+
+### Transaction Builders (build + submit)
+
+| Method | Description |
+|--------|-------------|
+| `transfer({ from, to, amount, nonce, signFn })` | Build + send a Transfer TX |
+| `stake({ staker, validator, amount, signFn })` | Build + send a Stake TX |
+| `unstake({ stakeAccount, amount, signFn })` | Build + send an Unstake TX |
+| `claimRewards({ stakeAccount, signFn })` | Build + send a ClaimRewards TX |
+| `createNFT({ creator, metadataUrl, royalties, signFn })` | Build + send a CreateNFT TX |
+| `transferNFT({ from, nftId, to, signFn })` | Build + send a TransferNFT TX |
+| `updateMetadata({ creator, nftId, metadataUrl, signFn })` | Build + send an UpdateMetadata TX |
+
+Each builder fetches a fresh `blockhash` + current `slot` from the chain, then submits the signed transaction via `sendTransaction()`. All steps are real RPC calls.
+
+## Convenience Functions
+
+```javascript
+// All of these use the default RPC (http://127.0.0.1:8899)
+const slot = await aether.getSlot();
+const balance = await aether.getBalance('ATH...');
+const epoch = await aether.getEpoch();
+const tps = await aether.getTPS();
+const supply = await aether.getSupply();
+const fees = await aether.getFees();
+const validators = await aether.getValidators();
+const peers = await aether.getPeers();
+const health = await aether.getHealth();
+const { blockhash } = await aether.getRecentBlockhash();
+const tx = await aether.getTransaction('sig...');
+const txs = await aether.getRecentTransactions('ATH...', 20);
+const stakePos = await aether.getStakePositions('ATH...');
+const rewards = await aether.getRewards('ATH...');
+const tokenAccts = await aether.getTokenAccounts('ATH...');
+const stakeAccts = await aether.getStakeAccounts('ATH...');
+const apy = await aether.getValidatorAPY('validatorAddr');
+const pingResult = await aether.ping(); // { ok, latency, rpc }
+```
+
+## Utilities
+
+| Function | Description |
+|----------|-------------|
+| `createClient(options)` | Factory: create an `AetherClient` instance |
+| `ping(rpcUrl?)` | Ping RPC, returns `{ ok, latency, rpc }` |
+| `rpcGet(rpcUrl, path, timeout?)` | Low-level GET |
+| `rpcPost(rpcUrl, path, body, timeout?)` | Low-level POST |
+| `DEFAULT_RPC_URL` | `"http://127.0.0.1:8899"` |
+| `DEFAULT_TIMEOUT_MS` | `10000` |
+
+## CLI Integration
+
+The SDK is wired into these CLI commands in `aether-cli`:
+
+| CLI Command | SDK Method Used |
+|-------------|----------------|
+| `aether status` | `getEpochInfo`, `getSupply`, `getSlot`, `getBlockHeight`, `getClusterPeers`, `getVersion`, `getStakePositions`, `getRewards` |
+| `aether network` | `getSlot`, `getBlockHeight`, `getClusterPeers`, `getValidators`, `getEpochInfo`, `getSupply`, `getTPS` |
+| `aether blockhash` | `getRecentBlockhash` |
+| `aether fees` | `getFees`, `getRecentBlockhash` |
+| `aether tps` | `getTPS`, `getSlot` |
+| `aether account` | `getAccountInfo`, `getBalance`, `getRecentTransactions`, `getStakePositions`, `getTokenAccounts`, `getStakeAccounts` |
+
+## Configuration
+
+```bash
+# Environment variable
+export AETHER_RPC=http://127.0.0.1:8899
+
+# Or per-call
+const client = new aether.AetherClient({ rpcUrl: 'http://custom:8899' });
+```
+
+## Example: Full Dashboard
+
+```javascript
+const aether = require('@jellylegsai/aether-sdk');
+
+async function dashboard() {
+  const [slot, blockHeight, tps, supply, { blockhash }] = await Promise.all([
+    aether.getSlot(),
+    aether.getBlockHeight(),
+    aether.getTPS(),
+    aether.getSupply(),
+    aether.getRecentBlockhash(),
+  ]);
+
+  console.log('=== Aether Network Dashboard ===');
+  console.log(`Slot:              ${slot}`);
+  console.log(`Block:             ${blockHeight}`);
+  console.log(`TPS:               ${tps}`);
+  console.log(`Total Supply:      ${supply.total}`);
+  console.log(`Blockhash:         ${blockhash}`);
+}
+
+dashboard();
+```
+
+## Example: Check Staking Rewards
+
+```javascript
+const aether = require('@jellylegsai/aether-sdk');
+
+async function checkRewards(walletAddress) {
+  const [stakePositions, rewards] = await Promise.all([
+    aether.getStakePositions(walletAddress),
+    aether.getRewards(walletAddress),
+  ]);
+
+  console.log(`Stake positions: ${stakePositions.length}`);
+  console.log(`Total rewards:   ${rewards.total || rewards.amount} lamports`);
+}
+
+checkRewards('ATH...');
+```
+
+## License
+
+MIT © Jelly-legs AI Team