quantumcoin 6.14.4 → 7.0.1

package/generate-sdk.js

@@ -0,0 +1,888 @@
+#!/usr/bin/env node
+/**
+ * quantumcoin-sdk-generator
+ *
+ * NOTE: This script is the SDK generator CLI entrypoint.
+ *
+ * SPEC.md section 15: Typed Contract Generator
+ *
+ * Usage:
+ * - Non-interactive:
+ *   `node generate-sdk.js --abi path/to/abi.json --bin path/to/bytecode.bin --out ./out --name MyContract`
+ *
+ * - Interactive:
+ *   `node generate-sdk.js --abi path/to/abi.json --bin path/to/bytecode.bin`
+ */
+
+const fs = require("node:fs");
+const path = require("node:path");
+const readline = require("node:readline/promises");
+const { stdin, stdout } = require("node:process");
+const { execFileSync, spawnSync } = require("node:child_process");
+
+const { generate, generateFromArtifacts, generateTransactionalTestJs } = require("./src/generator");
+
+function _helpText() {
+  return `
+quantumcoin-sdk-generator (generate-sdk.js)
+
+Generates TypeScript contract wrappers (plus optional package scaffold, examples and transactional tests).
+
+If you run this script with no parameters, it prints this help.
+
+USAGE
+  node generate-sdk.js [options]
+
+INPUT MODES
+  1) ABI + BIN (bytecode)
+     --abi <path/to/Contract.abi.json>
+     --bin <path/to/Contract.bin>
+     --name <ContractName>        (optional; defaults from ABI filename)
+
+  2) Solidity (.sol) sources
+     --sol "<A.sol,B.sol,...>"    (comma-separated list; can be 1+ files)
+     --name <ContractName>        (optional; if omitted, generates ALL deployable contracts found)
+     --solc <path/to/solc.exe>    (optional; defaults from env; see ENV below)
+
+  3) Artifacts JSON (array of ABI+BIN pairs)
+     --artifacts-json <path/to/artifacts.json>
+       The JSON file should be an array. Each entry supports:
+         - { abi: "<path|abiArray>", bin: "<path|0x...>", name?: "<ContractName>" }
+       If "name" is omitted and abi is a path, the contract name defaults from the ABI filename.
+
+PACKAGE OUTPUT (optional)
+  --create-package
+  --package-dir <folder>
+  --package-name <name>
+  --package-description <text>
+  --package-author <text>
+  --package-license <spdx>        (default: MIT)
+  --package-version <semver>      (default: 0.0.1)
+
+  Notes:
+  - When --create-package is used, the generator creates a complete npm package scaffold with:
+    - src/*.ts (typed contracts + factories)
+    - test/e2e/*.e2e.test.js (transactional tests)
+    - examples/ (deploy/read/write/events)
+    - artifacts/ (only when using --sol)
+    - index.js + index.d.ts + README.md (generated by build scripts)
+  - The generator will run:
+      npm install
+      npm run build:ts
+      npm run build-powershell (Windows) or npm run build (non-Windows)
+    as the final step, so README.md and index.d.ts are produced immediately.
+
+GENERAL OPTIONS
+  --out <folder>                 Output folder (default: ./generated-contract)
+  --non-interactive | --yes      Disable prompts (required for CI)
+  -h | --help                    Show this help
+
+ENVIRONMENT
+  QC_SOLC_PATH / SOLC / SOLC_PATH
+    Path to solc executable used when compiling Solidity.
+    Default: c:\\solc\\solc.exe
+
+  QC_RPC_URL / QC_CHAIN_ID
+    Used by the auto-generated transactional tests in the generated package.
+
+EXAMPLES
+  Generate typed files from ABI+BIN into ./out:
+    node generate-sdk.js --abi .\\artifacts\\MyContract.abi.json --bin .\\artifacts\\MyContract.bin --out .\\out --name MyContract --non-interactive
+
+  Generate a new typed package from ABI+BIN:
+    node generate-sdk.js --abi .\\My.abi.json --bin .\\My.bin --name MyContract --create-package --package-dir .\\tmp --package-name my-typed-contract --package-description "My typed contract" --package-author "me" --non-interactive
+
+  Generate a new typed package from Solidity (single file):
+    set QC_SOLC_PATH=c:\\solc\\solc.exe
+    node generate-sdk.js --sol ".\\contracts\\MyContract.sol" --create-package --package-dir .\\tmp --package-name my-typed-contract --package-description "My typed contract" --package-author "me" --non-interactive
+
+  Generate a new typed package from Solidity (multiple files):
+    node generate-sdk.js --sol ".\\contracts\\A.sol,.\\contracts\\B.sol,.\\contracts\\lib\\C.sol" --create-package --package-dir .\\tmp --package-name my-typed-contract --package-description "My typed contract" --package-author "me" --non-interactive
+
+`.trimStart();
+}
+
+function _argValue(argv, name) {
+  const idx = argv.indexOf(name);
+  if (idx === -1) return null;
+  return argv[idx + 1] || null;
+}
+
+function _hasFlag(argv, name) {
+  return argv.includes(name);
+}
+
+function _basenameNoExt(p) {
+  const b = path.basename(p);
+  const i = b.lastIndexOf(".");
+  return i === -1 ? b : b.slice(0, i);
+}
+
+function _defaultContractNameFromAbiPath(abiPath) {
+  const b = path.basename(abiPath);
+  if (/\.abi\.json$/i.test(b)) return b.replace(/\.abi\.json$/i, "");
+  return _basenameNoExt(abiPath);
+}
+
+function _ensureDir(p) {
+  fs.mkdirSync(p, { recursive: true });
+}
+
+function _readRootDependencies() {
+  const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, "package.json"), "utf8"));
+  return pkg.dependencies || {};
+}
+
+function _readRootPackageJson() {
+  return JSON.parse(fs.readFileSync(path.join(__dirname, "package.json"), "utf8"));
+}
+
+function _readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, "utf8"));
+}
+
+function _looksLikeHex(s) {
+  if (typeof s !== "string") return false;
+  const t = s.trim();
+  if (!t) return false;
+  if (t.startsWith("0x")) return /^0x[0-9a-fA-F]*$/.test(t);
+  return /^[0-9a-fA-F]*$/.test(t);
+}
+
+function _readArtifactsJson(fileAbs) {
+  const baseDir = path.dirname(fileAbs);
+  const parsed = _readJson(fileAbs);
+  if (!Array.isArray(parsed)) throw new Error(`Artifacts JSON must be an array: ${fileAbs}`);
+
+  /** @type {Array<{ contractName: string, abi: any[], bytecode: string, docs?: any }>} */
+  const artifacts = [];
+
+  for (let i = 0; i < parsed.length; i++) {
+    const entry = parsed[i];
+    if (!entry || typeof entry !== "object") throw new Error(`Invalid artifacts entry at index ${i} (expected object)`);
+
+    const abiField = entry.abi ?? entry.abiPath;
+    const binField = entry.bin ?? entry.bytecode ?? entry.binPath ?? entry.bytecodePath;
+    const nameField = entry.name ?? entry.contractName;
+
+    let abi;
+    let abiPath = null;
+    if (typeof abiField === "string") {
+      abiPath = path.resolve(baseDir, abiField);
+      if (!fs.existsSync(abiPath)) throw new Error(`ABI file not found (entry ${i}): ${abiPath}`);
+      abi = _readJson(abiPath);
+    } else if (Array.isArray(abiField)) {
+      abi = abiField;
+    } else {
+      throw new Error(`Invalid "abi" for artifacts entry ${i} (expected path or ABI array)`);
+    }
+    if (!Array.isArray(abi)) throw new Error(`ABI must be an array (entry ${i})`);
+
+    let bytecodeRaw;
+    if (typeof binField === "string") {
+      const maybePath = path.resolve(baseDir, binField);
+      if (fs.existsSync(maybePath) && fs.statSync(maybePath).isFile()) {
+        bytecodeRaw = fs.readFileSync(maybePath, "utf8").trim();
+      } else if (_looksLikeHex(binField)) {
+        bytecodeRaw = binField.trim();
+      } else {
+        throw new Error(`BIN/bytecode file not found (entry ${i}): ${maybePath}`);
+      }
+    } else {
+      throw new Error(`Invalid "bin" for artifacts entry ${i} (expected path or hex string)`);
+    }
+
+    const bytecode = bytecodeRaw.startsWith("0x") ? bytecodeRaw : `0x${bytecodeRaw}`;
+
+    let contractName = null;
+    if (typeof nameField === "string" && nameField.trim()) {
+      contractName = _cap(nameField.trim());
+    } else if (abiPath) {
+      contractName = _cap(_defaultContractNameFromAbiPath(abiPath));
+    } else {
+      throw new Error(`Missing contract name for artifacts entry ${i}. Provide "name" or use abi as a path.`);
+    }
+
+    artifacts.push({ contractName, abi, bytecode, docs: null });
+  }
+
+  // Ensure stable ordering and unique names
+  artifacts.sort((a, b) => a.contractName.localeCompare(b.contractName));
+  const seen = new Set();
+  for (const a of artifacts) {
+    if (seen.has(a.contractName)) throw new Error(`Duplicate contractName in artifacts JSON: ${a.contractName}`);
+    seen.add(a.contractName);
+  }
+
+  if (artifacts.length === 0) throw new Error("Artifacts JSON contained no entries.");
+  return artifacts;
+}
+
+function _rewriteFileDepsToAbsolute(deps, rootDir) {
+  const out = { ...deps };
+  for (const [name, ver] of Object.entries(out)) {
+    if (typeof ver === "string" && ver.startsWith("file:")) {
+      const rel = ver.slice("file:".length);
+      const abs = path.resolve(rootDir, rel);
+      out[name] = `file:${abs.replace(/\\\\/g, "/")}`;
+    }
+  }
+  return out;
+}
+
+function _writeJson(filePath, obj) {
+  fs.writeFileSync(filePath, JSON.stringify(obj, null, 2) + "\n", "utf8");
+}
+
+function _writeText(filePath, content) {
+  fs.writeFileSync(filePath, content, "utf8");
+}
+
+function _findConstructor(abi) {
+  const ctor = (abi || []).find((f) => f && f.type === "constructor");
+  return ctor || { type: "constructor", inputs: [] };
+}
+
+function _solTypeToExampleValueExpr(type) {
+  if (typeof type !== "string") return "undefined";
+  if (type.endsWith("]")) {
+    const inner = type.slice(0, type.lastIndexOf("["));
+    return `[${_solTypeToExampleValueExpr(inner)}]`;
+  }
+  if (type === "address") return "wallet.address";
+  if (type === "bool") return "true";
+  if (type === "string") return JSON.stringify("hello");
+  if (type === "bytes") return JSON.stringify("0x");
+  if (type === "bytes32") return `encodeBytes32String("init")`;
+  if (type.startsWith("uint") || type.startsWith("int")) return "123n";
+  return "undefined";
+}
+
+function _parseCommaSeparatedFiles(v) {
+  if (!v) return [];
+  return v
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+function _resolveSolcPath(argv) {
+  const solcArg = _argValue(argv, "--solc") || _argValue(argv, "--solc-path") || _argValue(argv, "--solcPath");
+  const env =
+    solcArg ||
+    process.env.QC_SOLC_PATH ||
+    process.env.SOLC ||
+    process.env.SOLC_PATH ||
+    process.env.solc ||
+    null;
+  return env || "c:\\gethbuild\\solc.exe";
+}
+
+function _assertSolcExists(solcPath) {
+  if (!fs.existsSync(solcPath)) {
+    throw new Error(
+      `solc not found at ${solcPath}. Set env QC_SOLC_PATH or SOLC (e.g. c:\\\\solc\\\\solc.exe) or pass --solc <path>.`,
+    );
+  }
+}
+
+function _compileSolidityToArtifacts({ solcPath, solFilesAbs, contractNameFilter }) {
+  _assertSolcExists(solcPath);
+  const out = execFileSync(solcPath, ["--optimize", "--combined-json", "abi,bin", ...solFilesAbs], { encoding: "utf8" });
+  const parsed = JSON.parse(out);
+
+  const artifacts = [];
+  for (const key of Object.keys(parsed.contracts || {})) {
+    const entry = parsed.contracts[key];
+    const name = key.includes(":") ? key.split(":").pop() : key;
+    if (!name) continue;
+    if (contractNameFilter && name !== contractNameFilter) continue;
+    const abi = entry && entry.abi ? JSON.parse(entry.abi) : null;
+    const bin = entry && typeof entry.bin === "string" ? entry.bin : "";
+    if (!abi || !Array.isArray(abi)) continue;
+    if (!bin) continue; // skip abstract/interfaces
+    artifacts.push({ contractName: name, abi, bytecode: bin.startsWith("0x") ? bin : `0x${bin}` });
+  }
+
+  if (contractNameFilter && artifacts.length === 0) {
+    throw new Error(`No compiled contract matched --name ${contractNameFilter}`);
+  }
+  if (artifacts.length === 0) {
+    throw new Error("No deployable contracts found in solc output (empty bytecode).");
+  }
+
+  // Stable ordering
+  artifacts.sort((a, b) => a.contractName.localeCompare(b.contractName));
+  return artifacts;
+}
+
+function _writeSolcArtifacts(outRoot, artifacts) {
+  const artifactsDir = path.join(outRoot, "artifacts");
+  _ensureDir(artifactsDir);
+  for (const a of artifacts) {
+    _writeText(path.join(artifactsDir, `${a.contractName}.abi.json`), JSON.stringify(a.abi, null, 2) + "\n");
+    _writeText(path.join(artifactsDir, `${a.contractName}.bin`), a.bytecode + "\n");
+  }
+}
+
+function _normalizeSolDoc(text) {
+  if (!text) return "";
+  return text
+    .split(/\r?\n/g)
+    .map((l) => l.trim())
+    .filter(Boolean)
+    .map((l) => {
+      // Normalize common NatSpec tags into plain text (but keep @param/@return as-is)
+      if (l.startsWith("@title ")) return l.slice("@title ".length).trim();
+      if (l.startsWith("@notice ")) return l.slice("@notice ".length).trim();
+      if (l.startsWith("@dev ")) return l.slice("@dev ".length).trim();
+      return l;
+    })
+    .filter(Boolean)
+    .join("\n")
+    .trim();
+}
+
+function _extractSolDocs(solFilesAbs) {
+  /** @type {Record<string, { contract?: string, functions: Record<string,string> }>} */
+  const out = {};
+
+  for (const file of solFilesAbs) {
+    const src = fs.readFileSync(file, "utf8");
+    const lines = src.split(/\r?\n/g);
+
+    let pending = [];
+    let inBlock = false;
+    let currentContract = null;
+
+    const flushPending = () => {
+      const s = _normalizeSolDoc(pending.join("\n"));
+      pending = [];
+      return s;
+    };
+
+    for (let i = 0; i < lines.length; i++) {
+      const raw = lines[i];
+      const t = raw.trim();
+
+      if (inBlock) {
+        // Capture block comment content lines, stripping leading '*' and the closing '*/'
+        const endIdx = raw.indexOf("*/");
+        const content = endIdx !== -1 ? raw.slice(0, endIdx) : raw;
+        const cleaned = content.replace(/^\s*\*\s?/, "").trim();
+        if (cleaned) pending.push(cleaned);
+        if (endIdx !== -1) inBlock = false;
+        continue;
+      }
+
+      // Solidity NatSpec / doc comments
+      if (t.startsWith("/**")) {
+        inBlock = true;
+        // Capture anything after '/**' on the same line and handle one-line comments.
+        const startIdx = raw.indexOf("/**") + 3;
+        const rest = raw.slice(startIdx);
+        const endIdx = rest.indexOf("*/");
+        const content = endIdx !== -1 ? rest.slice(0, endIdx) : rest;
+        const cleaned = content.replace(/^\s*\*\s?/, "").trim();
+        if (cleaned) pending.push(cleaned);
+        if (endIdx !== -1) inBlock = false;
+        continue;
+      }
+      if (t.startsWith("///")) {
+        pending.push(t.slice(3).trim());
+        continue;
+      }
+
+      // Skip empty lines without breaking pending docs
+      if (!t) continue;
+
+      // Contract/interface/library declaration
+      const cMatch = t.match(/^(contract|interface|library)\s+([A-Za-z_][A-Za-z0-9_]*)\b/);
+      if (cMatch) {
+        const name = cMatch[2];
+        const doc = flushPending();
+        currentContract = name;
+        if (!out[name]) out[name] = { contract: "", functions: {} };
+        if (doc) out[name].contract = doc;
+        continue;
+      }
+
+      // Function declaration
+      const fMatch = t.match(/^function\s+([A-Za-z_][A-Za-z0-9_]*)\b/);
+      if (fMatch && currentContract) {
+        const fn = fMatch[1];
+        const doc = flushPending();
+        if (!out[currentContract]) out[currentContract] = { contract: "", functions: {} };
+        if (doc) out[currentContract].functions[fn] = doc;
+        continue;
+      }
+
+      // If we hit a real code line that's not a declaration, discard any pending doc
+      pending = [];
+    }
+  }
+
+  // Normalize all docs
+  for (const k of Object.keys(out)) {
+    out[k].contract = _normalizeSolDoc(out[k].contract || "");
+    for (const fn of Object.keys(out[k].functions || {})) {
+      out[k].functions[fn] = _normalizeSolDoc(out[k].functions[fn]);
+    }
+  }
+
+  return out;
+}
+
+function _renderPackageIndexJs({ artifacts }) {
+  const lines = [];
+  lines.push("/**");
+  lines.push(" * Auto-generated typed contract package.");
+  lines.push(" *");
+  lines.push(" * This file is used by `jsdoc-to-markdown` (jsdoc2md) to generate README.md.");
+  lines.push(" */");
+  lines.push("");
+  lines.push("const dist = require(\"./dist\");");
+  lines.push("Object.assign(exports, dist);");
+  lines.push("");
+
+  for (const a of artifacts) {
+    const doc = a.docs && typeof a.docs.contract === "string" ? a.docs.contract : "";
+    if (doc && doc.trim()) {
+      lines.push("/**");
+      for (const l of doc.split(/\r?\n/g)) {
+        const t = l.trim();
+        if (!t) continue;
+        lines.push(` * ${t}`);
+      }
+      lines.push(" */");
+    } else {
+      lines.push("/**");
+      lines.push(` * ${a.contractName}`);
+      lines.push(" */");
+    }
+    lines.push(`exports.${a.contractName} = dist.${a.contractName};`);
+    lines.push(`exports.${a.contractName}__factory = dist.${a.contractName}__factory;`);
+    lines.push("");
+  }
+
+  return lines.join("\n") + "\n";
+}
+
+function _quoteIfNeeded(s) {
+  if (typeof s !== "string") return s;
+  return /[ \t"]/g.test(s) ? `"${s.replace(/"/g, '\\"')}"` : s;
+}
+
+function _npmCmd() {
+  return process.platform === "win32" ? "npm.cmd" : "npm";
+}
+
+function _runNpm(args, cwd) {
+  if (process.platform === "win32") {
+    const cmd = `${_npmCmd()} ${args.map(_quoteIfNeeded).join(" ")}`;
+    const res = spawnSync("cmd.exe", ["/d", "/s", "/c", cmd], { cwd, encoding: "utf8", stdio: "inherit" });
+    if (res.error) throw res.error;
+    if (res.status !== 0) throw new Error(`npm command failed: ${cmd}`);
+    return;
+  }
+
+  const res = spawnSync(_npmCmd(), args, { cwd, encoding: "utf8", stdio: "inherit" });
+  if (res.error) throw res.error;
+  if (res.status !== 0) throw new Error(`npm command failed: ${_npmCmd()} ${args.join(" ")}`);
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+
+  if (argv.length === 0 || _hasFlag(argv, "--help") || _hasFlag(argv, "-h")) {
+    process.stdout.write(_helpText());
+    process.exitCode = 0;
+    return;
+  }
+
+  const abiPathArg = _argValue(argv, "--abi");
+  const binPathArg = _argValue(argv, "--bin");
+  const solArg = _argValue(argv, "--sol") || _argValue(argv, "--sol-files") || _argValue(argv, "--solFiles");
+  const artifactsJsonArg =
+    _argValue(argv, "--artifacts-json") || _argValue(argv, "--artifactsJson") || _argValue(argv, "--artifacts");
+  const outArg = _argValue(argv, "--out");
+  const nameArg = _argValue(argv, "--name");
+  const nonInteractive = _hasFlag(argv, "--non-interactive") || _hasFlag(argv, "--yes");
+  const createPackageFlag = _hasFlag(argv, "--create-package");
+  const pkgDirArg = _argValue(argv, "--package-dir");
+  const pkgNameArg = _argValue(argv, "--package-name");
+  const pkgDescArg = _argValue(argv, "--package-description") || "";
+  const pkgAuthorArg = _argValue(argv, "--package-author") || "";
+  const pkgLicenseArg = _argValue(argv, "--package-license") || "MIT";
+  const pkgVersionArg = _argValue(argv, "--package-version") || "0.0.1";
+
+  // Decide input type.
+  let inputType = null; // "abibin" | "sol" | "artifactsjson"
+  if (solArg) inputType = "sol";
+  if (artifactsJsonArg) inputType = inputType || "artifactsjson";
+  if (abiPathArg || binPathArg) inputType = inputType || "abibin";
+  if ((solArg ? 1 : 0) + (artifactsJsonArg ? 1 : 0) + (abiPathArg || binPathArg ? 1 : 0) > 1) {
+    throw new Error("Select only one input mode: --abi/--bin OR --sol OR --artifacts-json.");
+  }
+
+  let createPackage = false;
+  let outDir = outArg ? path.resolve(outArg) : null;
+  let contractName = nameArg || null;
+
+  // Interactive prompt: ask input type first.
+  let absAbi = null;
+  let absBin = null;
+  let solFilesAbs = [];
+  let artifactsJsonAbs = null;
+
+  if (!nonInteractive) {
+    const rl0 = readline.createInterface({ input: stdin, output: stdout });
+    try {
+      if (!inputType) {
+        const ans = (await rl0.question("Input type? (1) ABI+BIN  (2) SOL  (3) ARTIFACTS JSON  ")).trim();
+        inputType = ans === "2" ? "sol" : ans === "3" ? "artifactsjson" : "abibin";
+      }
+      if (inputType === "abibin") {
+        const abiP = abiPathArg || (await rl0.question("Enter ABI path (.json): ")).trim();
+        const binP = binPathArg || (await rl0.question("Enter bytecode path (.bin): ")).trim();
+        if (!abiP || !binP) throw new Error("Missing ABI/BIN paths.");
+        absAbi = path.resolve(abiP);
+        absBin = path.resolve(binP);
+        if (!fs.existsSync(absAbi)) throw new Error(`ABI file not found: ${absAbi}`);
+        if (!fs.existsSync(absBin)) throw new Error(`Bytecode file not found: ${absBin}`);
+        contractName = contractName || _cap(_defaultContractNameFromAbiPath(absAbi));
+      } else if (inputType === "sol") {
+        const solP = solArg || (await rl0.question("Enter Solidity file(s) (comma-separated): ")).trim();
+        const files = _parseCommaSeparatedFiles(solP);
+        if (files.length === 0) throw new Error("Missing Solidity file(s).");
+        solFilesAbs = files.map((p) => path.resolve(p));
+        for (const f of solFilesAbs) {
+          if (!fs.existsSync(f)) throw new Error(`Solidity file not found: ${f}`);
+        }
+        if (!contractName) {
+          const maybe = (await rl0.question("Contract name (optional; empty = generate all): ")).trim();
+          if (maybe) contractName = maybe;
+        }
+      } else {
+        const p = artifactsJsonArg || (await rl0.question("Enter artifacts JSON path (.json): ")).trim();
+        if (!p) throw new Error("Missing artifacts JSON path.");
+        artifactsJsonAbs = path.resolve(p);
+        if (!fs.existsSync(artifactsJsonAbs)) throw new Error(`Artifacts JSON file not found: ${artifactsJsonAbs}`);
+      }
+    } finally {
+      rl0.close();
+    }
+  }
+
+  // Non-interactive input validation
+  if (nonInteractive) {
+    if (!inputType) {
+      throw new Error("Select an input type: pass --abi/--bin OR pass --sol <file1.sol,file2.sol> OR pass --artifacts-json <file.json>.");
+    }
+    if (inputType === "abibin") {
+      if (!abiPathArg || !binPathArg) {
+        throw new Error("Missing required arguments: --abi <path> --bin <path>");
+      }
+      absAbi = path.resolve(abiPathArg);
+      absBin = path.resolve(binPathArg);
+      if (!fs.existsSync(absAbi)) throw new Error(`ABI file not found: ${absAbi}`);
+      if (!fs.existsSync(absBin)) throw new Error(`Bytecode file not found: ${absBin}`);
+      contractName = contractName || _cap(_defaultContractNameFromAbiPath(absAbi));
+    } else if (inputType === "sol") {
+      const files = _parseCommaSeparatedFiles(solArg);
+      if (files.length === 0) throw new Error("Missing required argument: --sol <file1.sol,file2.sol>");
+      solFilesAbs = files.map((p) => path.resolve(p));
+      for (const f of solFilesAbs) {
+        if (!fs.existsSync(f)) throw new Error(`Solidity file not found: ${f}`);
+      }
+      // contractName can be null => generate all
+    } else {
+      if (!artifactsJsonArg) throw new Error("Missing required argument: --artifacts-json <path/to/artifacts.json>");
+      artifactsJsonAbs = path.resolve(artifactsJsonArg);
+      if (!fs.existsSync(artifactsJsonAbs)) throw new Error(`Artifacts JSON file not found: ${artifactsJsonAbs}`);
+    }
+  }
+
+  if (createPackageFlag) {
+    createPackage = true;
+  }
+
+  if (!nonInteractive && !createPackageFlag) {
+    const rl = readline.createInterface({ input: stdin, output: stdout });
+    try {
+      const ans = (await rl.question("Do you want to create a new package? (Y/N) ")).trim().toLowerCase();
+      createPackage = ans === "y" || ans === "yes";
+
+      if (createPackage) {
+        const pkgFolder = (await rl.question("Enter the folder path where the package should be created: ")).trim();
+        const pkgName = (await rl.question("Enter package name: ")).trim();
+        const pkgDesc = (await rl.question("Enter package description: ")).trim();
+        const pkgAuthor = (await rl.question("Enter author name: ")).trim();
+        const pkgLicense = (await rl.question("Enter license (default: MIT): ")).trim() || "MIT";
+        const pkgVersion = (await rl.question("Enter version (default: 0.0.1): ")).trim() || "0.0.1";
+
+        outDir = path.resolve(pkgFolder, pkgName);
+        _ensureDir(outDir);
+
+        _createPackageScaffold({
+          outDir,
+          pkgName,
+          pkgDesc,
+          pkgAuthor,
+          pkgLicense,
+          pkgVersion,
+        });
+      } else {
+        const target = (await rl.question("Enter the location in your existing package (relative to package root): ")).trim();
+        outDir = path.resolve(process.cwd(), target || "src/contracts");
+      }
+    } finally {
+      rl.close();
+    }
+  }
+
+  if (createPackage && nonInteractive) {
+    const pkgFolder = pkgDirArg ? path.resolve(pkgDirArg) : null;
+    const pkgName = pkgNameArg || null;
+    if (!pkgFolder || !pkgName) {
+      throw new Error("When using --create-package in non-interactive mode, pass --package-dir <dir> and --package-name <name>.");
+    }
+    outDir = path.resolve(pkgFolder, pkgName);
+    _ensureDir(outDir);
+    _createPackageScaffold({
+      outDir,
+      pkgName,
+      pkgDesc: pkgDescArg,
+      pkgAuthor: pkgAuthorArg,
+      pkgLicense: pkgLicenseArg,
+      pkgVersion: pkgVersionArg,
+    });
+  }
+
+  if (!outDir) outDir = path.resolve(process.cwd(), "generated-contract");
+
+  const targetSrcDir = createPackage ? path.join(outDir, "src") : outDir;
+  _ensureDir(targetSrcDir);
+
+  // Resolve compilation / artifacts
+  /** @type {Array<{ contractName: string, abi: any[], bytecode: string }>} */
+  let artifacts = [];
+  if (inputType === "abibin") {
+    const abi = _readJson(absAbi);
+    const bytecodeRaw = fs.readFileSync(absBin, "utf8").trim();
+    const bytecode = bytecodeRaw.startsWith("0x") ? bytecodeRaw : `0x${bytecodeRaw}`;
+    artifacts = [{ contractName, abi, bytecode, docs: null }];
+  } else if (inputType === "sol") {
+    const solcPath = _resolveSolcPath(argv);
+    artifacts = _compileSolidityToArtifacts({ solcPath, solFilesAbs, contractNameFilter: contractName });
+
+    // Attach Solidity doc comments (NatSpec) to artifacts
+    const docsByContract = _extractSolDocs(solFilesAbs);
+    for (const a of artifacts) {
+      a.docs = docsByContract[a.contractName] || null;
+    }
+
+    // As requested: emit ABI/BIN artifacts to disk
+    _writeSolcArtifacts(createPackage ? outDir : targetSrcDir, artifacts);
+  } else {
+    // Artifacts JSON
+    artifacts = _readArtifactsJson(artifactsJsonAbs || path.resolve(artifactsJsonArg));
+  }
+
+  if (artifacts.length === 1) {
+    // Keep the old API/behavior for single-contract generation.
+    const a = artifacts[0];
+    generateFromArtifacts({ outDir: targetSrcDir, artifacts: [a] });
+  } else {
+    generateFromArtifacts({ outDir: targetSrcDir, artifacts });
+  }
+
+  if (createPackage) {
+    _writeText(
+      path.join(outDir, "README.md"),
+      _packageReadme({
+        pkgName: pkgNameArg || path.basename(outDir),
+        pkgDesc: pkgDescArg,
+        contractNames: artifacts.map((a) => a.contractName),
+      }),
+    );
+
+    // Transactional tests (always per-contract)
+    _ensureDir(path.join(outDir, "test", "e2e"));
+    _ensureDir(path.join(outDir, "examples"));
+
+    for (const a of artifacts) {
+      _writeText(
+        path.join(outDir, "test", "e2e", `${a.contractName}.e2e.test.js`),
+        generateTransactionalTestJs({ contractName: a.contractName, abi: a.abi }),
+      );
+    }
+
+    if (artifacts.length === 1) {
+      // Back-compat: keep original example filenames for a single-contract package.
+      const a = artifacts[0];
+      const ctor = _findConstructor(a.abi);
+      const ctorArgsExpr = (ctor.inputs || []).map((i) => _solTypeToExampleValueExpr(i.type)).join(", ");
+
+      _writeText(
+        path.join(outDir, "examples", "deploy.ts"),
+        `import { Initialize } from "quantumcoin/config";\nimport { JsonRpcProvider, Wallet, encodeBytes32String } from "quantumcoin";\nimport { ${a.contractName}__factory } from "../src";\n\nasync function main() {\n  const rpcUrl = process.env.QC_RPC_URL || "http://127.0.0.1:8545";\n  const chainId = process.env.QC_CHAIN_ID ? Number(process.env.QC_CHAIN_ID) : 123123;\n  await Initialize(null);\n\n  const provider = new JsonRpcProvider(rpcUrl, chainId);\n  const wallet = Wallet.createRandom().connect(provider);\n\n  const factory = new ${a.contractName}__factory(wallet);\n  const contract = await factory.deploy(${ctorArgsExpr}${ctorArgsExpr ? ", " : ""}{ gasLimit: 600000 });\n  const tx = contract.deployTransaction();\n  if (tx) await tx.wait();\n\n  console.log("Deployed at:", contract.target);\n}\n\nmain().catch((e) => {\n  console.error(e);\n  process.exitCode = 1;\n});\n`,
+      );
+
+      _writeText(
+        path.join(outDir, "examples", "read-operations.ts"),
+        `import { Initialize } from "quantumcoin/config";\nimport { JsonRpcProvider } from "quantumcoin";\nimport { ${a.contractName} } from "../src";\n\nasync function main() {\n  const rpcUrl = process.env.QC_RPC_URL || "http://127.0.0.1:8545";\n  const chainId = process.env.QC_CHAIN_ID ? Number(process.env.QC_CHAIN_ID) : 123123;\n  const address = process.env.CONTRACT_ADDRESS || "0x...";\n  await Initialize(null);\n\n  const provider = new JsonRpcProvider(rpcUrl, chainId);\n  const contract = ${a.contractName}.connect(address, provider);\n\n  console.log("Contract:", contract.target);\n}\n\nmain().catch((e) => {\n  console.error(e);\n  process.exitCode = 1;\n});\n`,
+      );
+
+      _writeText(
+        path.join(outDir, "examples", "write-operations.ts"),
+        `import { Initialize } from "quantumcoin/config";\nimport { JsonRpcProvider, Wallet } from "quantumcoin";\nimport { ${a.contractName} } from "../src";\n\nasync function main() {\n  const rpcUrl = process.env.QC_RPC_URL || "http://127.0.0.1:8545";\n  const chainId = process.env.QC_CHAIN_ID ? Number(process.env.QC_CHAIN_ID) : 123123;\n  const address = process.env.CONTRACT_ADDRESS || "0x...";\n  await Initialize(null);\n\n  const provider = new JsonRpcProvider(rpcUrl, chainId);\n  const wallet = Wallet.createRandom().connect(provider);\n  const contract = ${a.contractName}.connect(address, wallet);\n\n  // const tx = await contract.someWriteMethod(/* args */);\n  // await tx.wait();\n  console.log("Done");\n}\n\nmain().catch((e) => {\n  console.error(e);\n  process.exitCode = 1;\n});\n`,
+      );
+
+      _writeText(
+        path.join(outDir, "examples", "events.ts"),
+        `import { Initialize } from "quantumcoin/config";\nimport { JsonRpcProvider } from "quantumcoin";\nimport { ${a.contractName} } from "../src";\n\nasync function main() {\n  const rpcUrl = process.env.QC_RPC_URL || "http://127.0.0.1:8545";\n  const chainId = process.env.QC_CHAIN_ID ? Number(process.env.QC_CHAIN_ID) : 123123;\n  const address = process.env.CONTRACT_ADDRESS || "0x...";\n  await Initialize(null);\n\n  const provider = new JsonRpcProvider(rpcUrl, chainId);\n  const contract = ${a.contractName}.connect(address, provider);\n\n  console.log("Contract:", contract.target);\n}\n\nmain().catch((e) => {\n  console.error(e);\n  process.exitCode = 1;\n});\n`,
+      );
+    } else {
+      // Multi-contract: avoid filename collisions.
+      for (const a of artifacts) {
+        const ctor = _findConstructor(a.abi);
+        const ctorArgsExpr = (ctor.inputs || []).map((i) => _solTypeToExampleValueExpr(i.type)).join(", ");
+
+        _writeText(
+          path.join(outDir, "examples", `deploy-${a.contractName}.ts`),
+          `import { Initialize } from "quantumcoin/config";\nimport { JsonRpcProvider, Wallet, encodeBytes32String } from "quantumcoin";\nimport { ${a.contractName}__factory } from "../src";\n\nasync function main() {\n  const rpcUrl = process.env.QC_RPC_URL || "http://127.0.0.1:8545";\n  const chainId = process.env.QC_CHAIN_ID ? Number(process.env.QC_CHAIN_ID) : 123123;\n  await Initialize(null);\n\n  const provider = new JsonRpcProvider(rpcUrl, chainId);\n  const wallet = Wallet.createRandom().connect(provider);\n\n  const factory = new ${a.contractName}__factory(wallet);\n  const contract = await factory.deploy(${ctorArgsExpr}${ctorArgsExpr ? ", " : ""}{ gasLimit: 600000 });\n  const tx = contract.deployTransaction();\n  if (tx) await tx.wait();\n\n  console.log("Deployed ${a.contractName} at:", contract.target);\n}\n\nmain().catch((e) => {\n  console.error(e);\n  process.exitCode = 1;\n});\n`,
+        );
+
+        _writeText(
+          path.join(outDir, "examples", `read-operations-${a.contractName}.ts`),
+          `import { Initialize } from "quantumcoin/config";\nimport { JsonRpcProvider } from "quantumcoin";\nimport { ${a.contractName} } from "../src";\n\nasync function main() {\n  const rpcUrl = process.env.QC_RPC_URL || "http://127.0.0.1:8545";\n  const chainId = process.env.QC_CHAIN_ID ? Number(process.env.QC_CHAIN_ID) : 123123;\n  const address = process.env.CONTRACT_ADDRESS || "0x...";\n  await Initialize(null);\n\n  const provider = new JsonRpcProvider(rpcUrl, chainId);\n  const contract = ${a.contractName}.connect(address, provider);\n\n  console.log("${a.contractName}:", contract.target);\n}\n\nmain().catch((e) => {\n  console.error(e);\n  process.exitCode = 1;\n});\n`,
+        );
+
+        _writeText(
+          path.join(outDir, "examples", `write-operations-${a.contractName}.ts`),
+          `import { Initialize } from "quantumcoin/config";\nimport { JsonRpcProvider, Wallet } from "quantumcoin";\nimport { ${a.contractName} } from "../src";\n\nasync function main() {\n  const rpcUrl = process.env.QC_RPC_URL || "http://127.0.0.1:8545";\n  const chainId = process.env.QC_CHAIN_ID ? Number(process.env.QC_CHAIN_ID) : 123123;\n  const address = process.env.CONTRACT_ADDRESS || "0x...";\n  await Initialize(null);\n\n  const provider = new JsonRpcProvider(rpcUrl, chainId);\n  const wallet = Wallet.createRandom().connect(provider);\n  const contract = ${a.contractName}.connect(address, wallet);\n\n  // const tx = await contract.someWriteMethod(/* args */);\n  // await tx.wait();\n  console.log("Done");\n}\n\nmain().catch((e) => {\n  console.error(e);\n  process.exitCode = 1;\n});\n`,
+        );
+
+        _writeText(
+          path.join(outDir, "examples", `events-${a.contractName}.ts`),
+          `import { Initialize } from "quantumcoin/config";\nimport { JsonRpcProvider } from "quantumcoin";\nimport { ${a.contractName} } from "../src";\n\nasync function main() {\n  const rpcUrl = process.env.QC_RPC_URL || "http://127.0.0.1:8545";\n  const chainId = process.env.QC_CHAIN_ID ? Number(process.env.QC_CHAIN_ID) : 123123;\n  const address = process.env.CONTRACT_ADDRESS || "0x...";\n  await Initialize(null);\n\n  const provider = new JsonRpcProvider(rpcUrl, chainId);\n  const contract = ${a.contractName}.connect(address, provider);\n\n  console.log("${a.contractName}:", contract.target);\n}\n\nmain().catch((e) => {\n  console.error(e);\n  process.exitCode = 1;\n});\n`,
+        );
+      }
+    }
+
+    // Write an index.js for jsdoc-to-markdown, then install and run build scripts.
+    _writeText(path.join(outDir, "index.js"), _renderPackageIndexJs({ artifacts }));
+  }
+
+  // Final step: after package creation, build docs/README.
+  if (createPackage) {
+    _runNpm(["install", "--no-fund", "--no-audit"], outDir);
+    _runNpm(["run", "build:ts"], outDir);
+    if (process.platform === "win32") {
+      _runNpm(["run", "build-powershell"], outDir);
+    } else {
+      _runNpm(["run", "build"], outDir);
+    }
+  }
+
+  console.log(`Generated contract files in: ${targetSrcDir}`);
+}
+
+function _cap(s) {
+  return s ? s[0].toUpperCase() + s.slice(1) : s;
+}
+
+function _packageReadme({ pkgName, pkgDesc, contractNames }) {
+  const list = (contractNames || []).map((n) => `- \`${n}\``).join("\n");
+  return `# ${pkgName}\n\n${pkgDesc}\n\n## Contracts\n\n${list || "- (none)"}\n\n## Running\n\n- \`npm install\`\n- \`npm test\`\n\nTransactional tests require:\n- \`QC_RPC_URL\`\n- \`QC_CHAIN_ID\` (optional)\n`;
+}
+
+function _createPackageScaffold({ outDir, pkgName, pkgDesc, pkgAuthor, pkgLicense, pkgVersion }) {
+  _ensureDir(outDir);
+  _ensureDir(path.join(outDir, "src"));
+  _ensureDir(path.join(outDir, "test", "e2e"));
+  _ensureDir(path.join(outDir, "examples"));
+
+  const rootPkg = _readRootPackageJson();
+  const rootDeps = _rewriteFileDepsToAbsolute(rootPkg.dependencies || {}, __dirname);
+
+  // Ensure the generated package depends on this repo's quantumcoin via absolute file path.
+  rootDeps.quantumcoin = `file:${__dirname.replace(/\\\\/g, "/")}`;
+  // Ensure docs tool is present (required by build scripts below).
+  if (!rootDeps["jsdoc-to-markdown"]) {
+    rootDeps["jsdoc-to-markdown"] = "latest";
+  }
+
+  const pkgJson = {
+    name: pkgName,
+    version: pkgVersion,
+    description: pkgDesc,
+    author: pkgAuthor,
+    license: pkgLicense,
+    main: "dist/index.js",
+    types: "dist/index.d.ts",
+    scripts: {
+      "build:ts": "npx -p typescript tsc -p tsconfig.json",
+      "build": "npx -p typescript tsc index.js --declaration --allowJs --emitDeclarationOnly && jsdoc2md index.js >README.md",
+      "build-powershell": "powershell npx -p typescript tsc index.js --declaration --allowJs --emitDeclarationOnly; jsdoc2md index.js >README.md",
+      test: "npm run build:ts && node --test --test-concurrency=1 \"test/**/*.test.js\"",
+      "test:e2e": "npm run build:ts && node --test --test-concurrency=1 \"test/e2e/**/*.test.js\"",
+    },
+    dependencies: rootDeps,
+    devDependencies: {},
+  };
+
+  _writeJson(path.join(outDir, "package.json"), pkgJson);
+  _writeJson(path.join(outDir, "tsconfig.json"), {
+    compilerOptions: {
+      target: "ES2022",
+      module: "CommonJS",
+      declaration: true,
+      outDir: "dist",
+      strict: true,
+      esModuleInterop: true,
+      skipLibCheck: true,
+    },
+    include: ["src/**/*.ts"],
+  });
+
+  _writeText(path.join(outDir, "README.md"), _packageReadme({ pkgName, pkgDesc, contractNames: [] }));
+
+  _writeText(path.join(outDir, ".gitignore"), `node_modules\n/dist\n*.log\n`);
+
+  // Minimal shims so the generated TypeScript can compile even though `quantumcoin`
+  // is a JavaScript package (no bundled .d.ts in this repo).
+  _writeText(
+    path.join(outDir, "src", "quantumcoin-shims.d.ts"),
+    `declare module "quantumcoin" {\n` +
+      `  export type ContractRunner = any;\n` +
+      `  export type TransactionResponse = any;\n` +
+      `  export type ContractTransactionResponse = any;\n` +
+      `  export type TransactionRequest = any;\n` +
+      `\n` +
+      `  export class Contract {\n` +
+      `    constructor(address: string, abi: any, runner?: any, bytecode?: any);\n` +
+      `    target: string;\n` +
+      `    address: string;\n` +
+      `    call(methodName: string, args: any[], overrides?: TransactionRequest): Promise<any>;\n` +
+      `    send(methodName: string, args: any[], overrides?: TransactionRequest): Promise<ContractTransactionResponse>;\n` +
+      `    deployTransaction(): TransactionResponse | null;\n` +
+      `  }\n` +
+      `\n` +
+      `  export class ContractFactory {\n` +
+      `    signer: any;\n` +
+      `    constructor(abi: any, bytecode: string, signer: any);\n` +
+      `    getDeployTransaction(...args: any[]): TransactionRequest;\n` +
+      `  }\n` +
+      `\n` +
+      `  export function getCreateAddress(opts: { from: string; nonce: number }): string;\n` +
+      `}\n`,
+  );
+}
+
+main().catch((e) => {
+  console.error(e);
+  process.exitCode = 1;
+});
+