@spectratools/etherscan-cli 0.2.0 → 0.2.2

package/README.md

@@ -21,6 +21,20 @@ etherscan-cli skills add
 etherscan-cli mcp add
 ```
 
+## ⚠️ Default Chain: Abstract
+
+All commands default to the **Abstract** chain (`--chain abstract`) when no `--chain` flag is provided. If you are querying Ethereum mainnet, you must explicitly pass `--chain ethereum`:
+
+```bash
+# Queries Abstract (default)
+etherscan-cli account balance 0x...
+
+# Queries Ethereum mainnet (explicit)
+etherscan-cli account balance 0x... --chain ethereum
+```
+
+Supported chains: `abstract`, `ethereum`, `base`, `arbitrum`, `optimism`, `polygon`, `avalanche`, `bsc`, `linea`, `scroll`, `zksync`, `mantle`, `blast`, `mode`, `sepolia`, `goerli`.
+
 ## Configuration
 
 ```bash

package/dist/cli.js

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { realpathSync } from "fs";
+import { readFileSync, realpathSync } from "fs";
+import { dirname, resolve } from "path";
 import { fileURLToPath } from "url";
 import { Cli as Cli7 } from "incur";
 
@@ -10,6 +11,7 @@ import {
   checksumAddress,
   createRateLimiter as createRateLimiter2,
   formatTimestamp,
+  isAddress,
   weiToEth,
   withRateLimit as withRateLimit2
 } from "@spectratools/cli-shared";
@@ -138,7 +140,9 @@ function resolveChainId(chain) {
 
 // src/commands/account.ts
 var rateLimiter = createRateLimiter2({ requestsPerSecond: 5 });
-var chainOption = z3.string().default(DEFAULT_CHAIN).describe("Chain name (abstract, ethereum, base, arbitrum, ...)");
+var chainOption = z3.string().default(DEFAULT_CHAIN).describe(
+  "Chain name (default: abstract). Options: ethereum, base, arbitrum, optimism, polygon, ..."
+);
 var txListItemSchema = z3.object({
   hash: z3.string(),
   from: z3.string(),
@@ -193,6 +197,12 @@ accountCli.command("balance", {
     }
   ],
   async run(c) {
+    if (!isAddress(c.args.address)) {
+      return c.error({
+        code: "INVALID_ADDRESS",
+        message: `Invalid address: "${c.args.address}". Use a valid 0x-prefixed 20-byte hex address.`
+      });
+    }
     const apiKey = c.env.ETHERSCAN_API_KEY;
     const chainId = resolveChainId(c.options.chain);
     const address = normalizeAddress(c.args.address);
@@ -212,10 +222,14 @@ accountCli.command("balance", {
     );
     return c.ok(
       { address, wei, eth: weiToEth(wei), chain: c.options.chain },
-      {
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
         cta: {
           commands: [
-            { command: "account txlist", args: { address }, description: "List transactions" },
+            {
+              command: "account txlist",
+              args: { address },
+              description: "List transactions"
+            },
             {
               command: "account tokentx",
               args: { address },
@@ -267,6 +281,12 @@ accountCli.command("txlist", {
     }
   ],
   async run(c) {
+    if (!isAddress(c.args.address)) {
+      return c.error({
+        code: "INVALID_ADDRESS",
+        message: `Invalid address: "${c.args.address}". Use a valid 0x-prefixed 20-byte hex address.`
+      });
+    }
     const apiKey = c.env.ETHERSCAN_API_KEY;
     const chainId = resolveChainId(c.options.chain);
     const address = normalizeAddress(c.args.address);
@@ -302,7 +322,7 @@ accountCli.command("txlist", {
     const firstHash = formatted[0]?.hash;
     return c.ok(
       { address, chain: c.options.chain, count: formatted.length, transactions: formatted },
-      {
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
         cta: {
           commands: firstHash ? [
             {
@@ -354,6 +374,12 @@ accountCli.command("tokentx", {
     }
   ],
   async run(c) {
+    if (!isAddress(c.args.address)) {
+      return c.error({
+        code: "INVALID_ADDRESS",
+        message: `Invalid address: "${c.args.address}". Use a valid 0x-prefixed 20-byte hex address.`
+      });
+    }
     const apiKey = c.env.ETHERSCAN_API_KEY;
     const chainId = resolveChainId(c.options.chain);
     const address = normalizeAddress(c.args.address);
@@ -386,7 +412,7 @@ accountCli.command("tokentx", {
     }));
     return c.ok(
       { address, chain: c.options.chain, count: formatted.length, transfers: formatted },
-      {
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
         cta: {
           commands: [
             {
@@ -424,6 +450,18 @@ accountCli.command("tokenbalance", {
     }
   ],
   async run(c) {
+    if (!isAddress(c.args.address)) {
+      return c.error({
+        code: "INVALID_ADDRESS",
+        message: `Invalid address: "${c.args.address}". Use a valid 0x-prefixed 20-byte hex address.`
+      });
+    }
+    if (!isAddress(c.options.contractaddress)) {
+      return c.error({
+        code: "INVALID_ADDRESS",
+        message: `Invalid contract address: "${c.options.contractaddress}". Use a valid 0x-prefixed 20-byte hex address.`
+      });
+    }
     const apiKey = c.env.ETHERSCAN_API_KEY;
     const chainId = resolveChainId(c.options.chain);
     const address = normalizeAddress(c.args.address);
@@ -445,7 +483,7 @@ accountCli.command("tokenbalance", {
     );
     return c.ok(
       { address, contract, balance, chain: c.options.chain },
-      {
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
         cta: {
           commands: [
             {
@@ -461,10 +499,17 @@ accountCli.command("tokenbalance", {
 });
 
 // src/commands/contract.ts
-import { checksumAddress as checksumAddress2, createRateLimiter as createRateLimiter3, withRateLimit as withRateLimit3 } from "@spectratools/cli-shared";
+import {
+  checksumAddress as checksumAddress2,
+  createRateLimiter as createRateLimiter3,
+  isAddress as isAddress2,
+  withRateLimit as withRateLimit3
+} from "@spectratools/cli-shared";
 import { Cli as Cli2, z as z4 } from "incur";
 var rateLimiter2 = createRateLimiter3({ requestsPerSecond: 5 });
-var chainOption2 = z4.string().default(DEFAULT_CHAIN).describe("Chain name (abstract, ethereum, base, arbitrum, ...)");
+var chainOption2 = z4.string().default(DEFAULT_CHAIN).describe(
+  "Chain name (default: abstract). Options: ethereum, base, arbitrum, optimism, polygon, ..."
+);
 var contractCli = Cli2.create("contract", {
   description: "Query contract ABI, source code, and deployment metadata."
 });
@@ -507,6 +552,12 @@ contractCli.command("abi", {
     }
   ],
   async run(c) {
+    if (!isAddress2(c.args.address)) {
+      return c.error({
+        code: "INVALID_ADDRESS",
+        message: `Invalid address: "${c.args.address}". Use a valid 0x-prefixed 20-byte hex address.`
+      });
+    }
     const apiKey = c.env.ETHERSCAN_API_KEY;
     const chainId = resolveChainId(c.options.chain);
     const address = checksumAddress2(c.args.address);
@@ -525,7 +576,7 @@ contractCli.command("abi", {
     );
     return c.ok(
       { address, chain: c.options.chain, abi: JSON.parse(abi) },
-      {
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
         cta: {
           commands: [
             {
@@ -569,6 +620,12 @@ contractCli.command("source", {
     }
   ],
   async run(c) {
+    if (!isAddress2(c.args.address)) {
+      return c.error({
+        code: "INVALID_ADDRESS",
+        message: `Invalid address: "${c.args.address}". Use a valid 0x-prefixed 20-byte hex address.`
+      });
+    }
     const apiKey = c.env.ETHERSCAN_API_KEY;
     const chainId = resolveChainId(c.options.chain);
     const address = checksumAddress2(c.args.address);
@@ -603,7 +660,7 @@ contractCli.command("source", {
         sourceCode: result.SourceCode,
         constructorArguments: result.ConstructorArguments
       },
-      {
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
         cta: {
           commands: [
             {
@@ -640,6 +697,12 @@ contractCli.command("creation", {
     }
   ],
   async run(c) {
+    if (!isAddress2(c.args.address)) {
+      return c.error({
+        code: "INVALID_ADDRESS",
+        message: `Invalid address: "${c.args.address}". Use a valid 0x-prefixed 20-byte hex address.`
+      });
+    }
     const apiKey = c.env.ETHERSCAN_API_KEY;
     const chainId = resolveChainId(c.options.chain);
     const address = checksumAddress2(c.args.address);
@@ -667,7 +730,7 @@ contractCli.command("creation", {
         txHash: result.txHash,
         chain: c.options.chain
       },
-      {
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
         cta: {
           commands: [
             {
@@ -686,7 +749,9 @@ contractCli.command("creation", {
 import { createRateLimiter as createRateLimiter4, withRateLimit as withRateLimit4 } from "@spectratools/cli-shared";
 import { Cli as Cli3, z as z5 } from "incur";
 var rateLimiter3 = createRateLimiter4({ requestsPerSecond: 5 });
-var chainOption3 = z5.string().default(DEFAULT_CHAIN).describe("Chain name (abstract, ethereum, base, arbitrum, ...)");
+var chainOption3 = z5.string().default(DEFAULT_CHAIN).describe(
+  "Chain name (default: abstract). Options: ethereum, base, arbitrum, optimism, polygon, ..."
+);
 var gasCli = Cli3.create("gas", {
   description: "Query gas oracle data and estimate confirmation latency."
 });
@@ -739,7 +804,7 @@ gasCli.command("oracle", {
         baseFee: `${oracle.suggestBaseFee} Gwei`,
         gasUsedRatio: oracle.gasUsedRatio
       },
-      {
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
         cta: {
           commands: [
             {
@@ -793,7 +858,7 @@ gasCli.command("estimate", {
         gasprice: c.options.gasprice,
         estimatedSeconds: estimate
       },
-      {
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
         cta: {
           commands: [
             {
@@ -811,7 +876,9 @@ gasCli.command("estimate", {
 import { createRateLimiter as createRateLimiter5, withRateLimit as withRateLimit5 } from "@spectratools/cli-shared";
 import { Cli as Cli4, z as z6 } from "incur";
 var rateLimiter4 = createRateLimiter5({ requestsPerSecond: 5 });
-var chainOption4 = z6.string().default(DEFAULT_CHAIN).describe("Chain name (abstract, ethereum, base, arbitrum, ...)");
+var chainOption4 = z6.string().default(DEFAULT_CHAIN).describe(
+  "Chain name (default: abstract). Options: ethereum, base, arbitrum, optimism, polygon, ..."
+);
 var statsCli = Cli4.create("stats", {
   description: "Query ETH price and total supply statistics."
 });
@@ -858,7 +925,7 @@ statsCli.command("ethprice", {
         usdTimestamp: new Date(Number(price.ethusd_timestamp) * 1e3).toISOString(),
         btcTimestamp: new Date(Number(price.ethbtc_timestamp) * 1e3).toISOString()
       },
-      {
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
         cta: {
           commands: [
             {
@@ -902,7 +969,7 @@ statsCli.command("ethsupply", {
         chain: c.options.chain,
         totalSupplyWei: supply
       },
-      {
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
         cta: {
           commands: [
             {
@@ -917,10 +984,17 @@ statsCli.command("ethsupply", {
 });
 
 // src/commands/token.ts
-import { checksumAddress as checksumAddress3, createRateLimiter as createRateLimiter6, withRateLimit as withRateLimit6 } from "@spectratools/cli-shared";
+import {
+  checksumAddress as checksumAddress3,
+  createRateLimiter as createRateLimiter6,
+  isAddress as isAddress3,
+  withRateLimit as withRateLimit6
+} from "@spectratools/cli-shared";
 import { Cli as Cli5, z as z7 } from "incur";
 var rateLimiter5 = createRateLimiter6({ requestsPerSecond: 5 });
-var chainOption5 = z7.string().default(DEFAULT_CHAIN).describe("Chain name (abstract, ethereum, base, arbitrum, ...)");
+var chainOption5 = z7.string().default(DEFAULT_CHAIN).describe(
+  "Chain name (default: abstract). Options: ethereum, base, arbitrum, optimism, polygon, ..."
+);
 var tokenCli = Cli5.create("token", {
   description: "Query token metadata, holders, and supply."
 });
@@ -982,6 +1056,12 @@ tokenCli.command("info", {
     }
   ],
   async run(c) {
+    if (!isAddress3(c.args.contractaddress)) {
+      return c.error({
+        code: "INVALID_ADDRESS",
+        message: `Invalid contract address: "${c.args.contractaddress}". Use a valid 0x-prefixed 20-byte hex address.`
+      });
+    }
     const apiKey = c.env.ETHERSCAN_API_KEY;
     const chainId = resolveChainId(c.options.chain);
     const address = checksumAddress3(c.args.contractaddress);
@@ -1015,7 +1095,7 @@ tokenCli.command("info", {
         website: info.website || void 0,
         description: info.description || void 0
       },
-      {
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
         cta: {
           commands: [
             {
@@ -1065,6 +1145,12 @@ tokenCli.command("holders", {
     }
   ],
   async run(c) {
+    if (!isAddress3(c.args.contractaddress)) {
+      return c.error({
+        code: "INVALID_ADDRESS",
+        message: `Invalid contract address: "${c.args.contractaddress}". Use a valid 0x-prefixed 20-byte hex address.`
+      });
+    }
     const apiKey = c.env.ETHERSCAN_API_KEY;
     const chainId = resolveChainId(c.options.chain);
     const address = checksumAddress3(c.args.contractaddress);
@@ -1095,7 +1181,7 @@ tokenCli.command("holders", {
         count: formatted.length,
         holders: formatted
       },
-      {
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
         cta: {
           commands: [
             {
@@ -1131,6 +1217,12 @@ tokenCli.command("supply", {
     }
   ],
   async run(c) {
+    if (!isAddress3(c.args.contractaddress)) {
+      return c.error({
+        code: "INVALID_ADDRESS",
+        message: `Invalid contract address: "${c.args.contractaddress}". Use a valid 0x-prefixed 20-byte hex address.`
+      });
+    }
     const apiKey = c.env.ETHERSCAN_API_KEY;
     const chainId = resolveChainId(c.options.chain);
     const address = checksumAddress3(c.args.contractaddress);
@@ -1149,7 +1241,7 @@ tokenCli.command("supply", {
     );
     return c.ok(
       { contractAddress: address, chain: c.options.chain, totalSupply: supply },
-      {
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
         cta: {
           commands: [
             {
@@ -1168,7 +1260,12 @@ tokenCli.command("supply", {
 import { createRateLimiter as createRateLimiter7, withRateLimit as withRateLimit7 } from "@spectratools/cli-shared";
 import { Cli as Cli6, z as z8 } from "incur";
 var rateLimiter6 = createRateLimiter7({ requestsPerSecond: 5 });
-var chainOption6 = z8.string().default(DEFAULT_CHAIN).describe("Chain name (abstract, ethereum, base, arbitrum, ...)");
+function hexToDecimal(hex) {
+  return BigInt(hex).toString();
+}
+var chainOption6 = z8.string().default(DEFAULT_CHAIN).describe(
+  "Chain name (default: abstract). Options: ethereum, base, arbitrum, optimism, polygon, ..."
+);
 var txCli = Cli6.create("tx", {
   description: "Query transaction details, receipts, and execution status."
 });
@@ -1197,7 +1294,7 @@ var transactionReceiptSchema = z8.object({
   logs: z8.array(z8.unknown())
 });
 var txStatusSchema = z8.object({
-  status: z8.string(),
+  isError: z8.string(),
   errDescription: z8.string()
 });
 txCli.command("info", {
@@ -1248,14 +1345,14 @@ txCli.command("info", {
         hash: tx.hash,
         from: tx.from,
         to: tx.to,
-        value: tx.value,
-        gas: tx.gas,
-        gasPrice: tx.gasPrice,
-        nonce: tx.nonce,
-        block: tx.blockNumber,
+        value: hexToDecimal(tx.value),
+        gas: hexToDecimal(tx.gas),
+        gasPrice: hexToDecimal(tx.gasPrice),
+        nonce: hexToDecimal(tx.nonce),
+        block: hexToDecimal(tx.blockNumber),
         chain: c.options.chain
       },
-      {
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
         cta: {
           commands: [
             {
@@ -1320,16 +1417,16 @@ txCli.command("receipt", {
     return c.ok(
       {
         hash: receipt.transactionHash,
-        block: receipt.blockNumber,
+        block: hexToDecimal(receipt.blockNumber),
         from: receipt.from,
         to: receipt.to,
         status: receipt.status === "0x1" ? "success" : "failed",
-        gasUsed: receipt.gasUsed,
+        gasUsed: hexToDecimal(receipt.gasUsed),
         contractAddress: receipt.contractAddress,
         logCount: receipt.logs.length,
         chain: c.options.chain
       },
-      {
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
         cta: {
           commands: [
             {
@@ -1374,7 +1471,7 @@ txCli.command("status", {
         {
           chainid: chainId,
           module: "transaction",
-          action: "gettxreceiptstatus",
+          action: "getstatus",
           txhash: c.args.txhash
         },
         txStatusSchema
@@ -1384,11 +1481,11 @@ txCli.command("status", {
     return c.ok(
       {
         hash: c.args.txhash,
-        status: result.status === "1" ? "success" : "failed",
+        status: result.isError === "0" ? "success" : "failed",
         error: result.errDescription || void 0,
         chain: c.options.chain
       },
-      {
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
         cta: {
           commands: [
             {
@@ -1404,7 +1501,10 @@ txCli.command("status", {
 });
 
 // src/cli.ts
+var __dirname = dirname(fileURLToPath(import.meta.url));
+var pkg = JSON.parse(readFileSync(resolve(__dirname, "../package.json"), "utf8"));
 var cli = Cli7.create("etherscan", {
+  version: pkg.version,
   description: "Query Etherscan API data from the command line."
 });
 cli.command(accountCli);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spectratools/etherscan-cli",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Etherscan API CLI for spectra-the-bot",
   "type": "module",
   "license": "MIT",