quantumcoin 6.14.5 → 7.0.2

package/test/unit/browser-provider.test.js

@@ -0,0 +1,82 @@
+/**
+ * @testCategory unit
+ * @blockchainRequired false
+ * @transactional false
+ * @description BrowserProvider (EIP-1193 wrapper) + debug event sink validation
+ */
+
+const { describe, it } = require("node:test");
+const assert = require("node:assert/strict");
+
+const qc = require("../../index");
+
+describe("BrowserProvider", () => {
+  it("wraps an EIP-1193 provider and emits debug events", async () => {
+    /** @type {any[]} */
+    const calls = [];
+
+    const fakeEip1193 = {
+      request: async ({ method, params }) => {
+        calls.push({ method, params });
+        if (method === "eth_accounts") {
+          return ["0x" + "11".repeat(32)];
+        }
+        if (method === "eth_blockNumber") {
+          return "0x10";
+        }
+        if (method === "eth_getBlockByNumber") {
+          // params: [ "latest", false ]
+          return {
+            number: "0x10",
+            hash: "0x" + "aa".repeat(32),
+            parentHash: "0x" + "bb".repeat(32),
+            timestamp: "0x1",
+            transactions: [],
+          };
+        }
+        throw new Error(`unsupported method: ${method}`);
+      },
+    };
+
+    const provider = new qc.BrowserProvider(fakeEip1193);
+
+    /** @type {any[]} */
+    const debug = [];
+    provider.on("debug", (ev) => debug.push(ev));
+
+    const bn = await provider.getBlockNumber();
+    assert.equal(bn, 16);
+
+    const latest = await provider.getBlock("latest");
+    assert.equal(latest.number, 16);
+    assert.ok(typeof latest.hash === "string");
+
+    const signer = await provider.getSigner();
+    const addr = await signer.getAddress();
+    assert.equal(addr.toLowerCase(), ("0x" + "11".repeat(32)).toLowerCase());
+    assert.equal(await provider.hasSigner(addr), true);
+
+    // Validate calls shape
+    assert.deepEqual(
+      calls.map((c) => c.method),
+      ["eth_blockNumber", "eth_getBlockByNumber", "eth_accounts", "eth_accounts"],
+    );
+
+    // Validate debug event sink: send+receive per request in order
+    const actions = debug.map((d) => d && d.action);
+    assert.deepEqual(actions, [
+      "sendEip1193Payload",
+      "receiveEip1193Result",
+      "sendEip1193Payload",
+      "receiveEip1193Result",
+      "sendEip1193Payload",
+      "receiveEip1193Result",
+      "sendEip1193Payload",
+      "receiveEip1193Result",
+    ]);
+
+    assert.equal(debug[0].payload.method, "eth_blockNumber");
+    assert.equal(debug[2].payload.method, "eth_getBlockByNumber");
+  });
+});
+

package/test/unit/contract.test.js

@@ -0,0 +1,82 @@
+/**
+ * @testCategory unit
+ * @blockchainRequired false
+ * @transactional false
+ * @description Contract behavior that can be tested offline (overrides, listeners)
+ */
+ 
+ const { describe, it } = require("node:test");
+ const assert = require("node:assert/strict");
+ 
+ const { Initialize } = require("../../config");
+ const qc = require("../../index");
+ 
+ describe("Contract", () => {
+   it("_invoke treats last arg as overrides only when object-like (null is NOT overrides)", async () => {
+     await Initialize(null);
+     const addr = qc.Wallet.createRandom().address;
+     const abi = [
+       { type: "function", name: "viewFn", stateMutability: "view", inputs: [{ name: "x", type: "uint256" }], outputs: [] },
+       { type: "function", name: "writeFn", stateMutability: "nonpayable", inputs: [{ name: "x", type: "uint256" }], outputs: [] },
+     ];
+ 
+     const c = new qc.Contract(addr, abi, null);
+ 
+     /** @type {any[]} */
+     const seen = [];
+     c.call = async (methodName, args, overrides) => {
+       seen.push({ kind: "call", methodName, args, overrides });
+       return "ok";
+     };
+     c.send = async (methodName, args, overrides) => {
+       seen.push({ kind: "send", methodName, args, overrides });
+       return { hash: "0x" + "22".repeat(32) };
+     };
+ 
+     // Overrides object extracted
+     await c._invoke("viewFn", [1n, { gasLimit: 123 }]);
+     // Passing null is NOT treated as overrides (it becomes a second argument)
+     await c._invoke("viewFn", [1n, null]);
+     // State-changing path chooses send()
+     await c._invoke("writeFn", [1n, { gasLimit: 456 }]);
+ 
+     assert.deepEqual(seen[0], { kind: "call", methodName: "viewFn", args: [1n], overrides: { gasLimit: 123 } });
+     assert.deepEqual(seen[1], { kind: "call", methodName: "viewFn", args: [1n, null], overrides: undefined });
+     assert.deepEqual(seen[2], { kind: "send", methodName: "writeFn", args: [1n], overrides: { gasLimit: 456 } });
+   });
+ 
+   it("removeAllListeners clears all when event omitted vs null, and clears one event when provided", async () => {
+     await Initialize(null);
+     const addr = qc.Wallet.createRandom().address;
+     const c = new qc.Contract(addr, [], null);
+ 
+     const cb1 = () => {};
+     const cb2 = () => {};
+     c.on("A", cb1);
+     c.on("B", cb2);
+ 
+     c.removeAllListeners("A");
+     // B remains
+     assert.equal(c._listeners.get("A")?.length || 0, 0);
+     assert.equal(c._listeners.get("B")?.length || 0, 1);
+ 
+     c.removeAllListeners(null); // treated as "no event"
+     assert.equal(c._listeners.size, 0);
+ 
+     c.on("C", cb1);
+     c.removeAllListeners(); // omitted => clear all
+     assert.equal(c._listeners.size, 0);
+   });
+ });
+ 
+ describe("ContractTransactionReceipt", () => {
+   it("getEvent/getEvents filter logs by eventName", () => {
+     const receipt = new qc.ContractTransactionReceipt({
+       logs: [{ eventName: "A", data: 1 }, { eventName: "B", data: 2 }, { eventName: "A", data: 3 }],
+     });
+     assert.deepEqual(receipt.getEvents("A").map((l) => l.data), [1, 3]);
+     assert.equal(receipt.getEvent("B").data, 2);
+     assert.equal(receipt.getEvent("Missing"), null);
+   });
+ });
+ 

package/test/unit/encoding-units-rlp.test.js

@@ -0,0 +1,89 @@
+/**
+ * @testCategory unit
+ * @blockchainRequired false
+ * @transactional false
+ * @description Encoding + units + RLP edge cases (optional params, negative paths)
+ */
+ 
+ const { describe, it } = require("node:test");
+ const assert = require("node:assert/strict");
+ 
+ const qc = require("../../index");
+ 
+ describe("Encoding", () => {
+   it("toHex/hexlify normalize strings and bytes", () => {
+     assert.equal(qc.toHex("0x0A"), "0x0a");
+     assert.equal(qc.hexlify(new Uint8Array([0x0a])), "0x0a");
+   });
+ 
+   it("concat concatenates and rejects non-array", () => {
+     const out = qc.concat([new Uint8Array([1, 2]), "0x03"]);
+     assert.equal(out, "0x010203");
+     assert.throws(() => qc.concat("nope"));
+   });
+ 
+   it("stripZerosLeft removes leading zeros", () => {
+     assert.equal(qc.stripZerosLeft("0x0000"), "0x");
+     assert.equal(qc.stripZerosLeft("0x000001"), "0x01");
+   });
+ 
+   it("zeroPad throws when value exceeds length", () => {
+     assert.throws(() => qc.zeroPad("0x1234", 1));
+     assert.equal(qc.zeroPad("0x12", 2), "0x0012");
+   });
+ 
+   it("base64 encode/decode roundtrip", () => {
+     const b = qc.toUtf8Bytes("hello");
+     const b64 = qc.encodeBase64(b);
+     const out = qc.decodeBase64(b64);
+     assert.equal(qc.toUtf8String(out), "hello");
+   });
+ 
+   it("isBytesLike returns true for hex and Uint8Array", () => {
+     assert.equal(qc.isBytesLike("0x1234"), true);
+     assert.equal(qc.isBytesLike(new Uint8Array([1, 2, 3])), true);
+     assert.equal(qc.isBytesLike("not-hex"), false);
+   });
+ 
+   it("solidityPacked helpers throw (not implemented)", () => {
+     assert.throws(() => qc.solidityPacked(), /not implemented/i);
+     assert.throws(() => qc.solidityPackedKeccak256(), /not implemented/i);
+     assert.throws(() => qc.solidityPackedSha256(), /not implemented/i);
+   });
+ });
+ 
+ describe("Units", () => {
+   it("parseUnits defaults decimals when omitted vs null", () => {
+     const a = qc.parseUnits("1.5");
+     const b = qc.parseUnits("1.5", null);
+     assert.equal(a, 1500000000000000000n);
+     assert.equal(a, b);
+   });
+ 
+   it("formatUnits defaults decimals when omitted vs null", () => {
+     const a = qc.formatUnits(1500000000000000000n);
+     const b = qc.formatUnits(1500000000000000000n, null);
+     assert.equal(a, "1.5");
+     assert.equal(a, b);
+   });
+ });
+ 
+ describe("RLP", () => {
+   it("decodeRlp rejects non-string input", () => {
+     assert.throws(() => qc.decodeRlp(123));
+   });
+ 
+   it("decodeRlp rejects trailing data", () => {
+     const encoded = qc.encodeRlp("0x01");
+     const withTrailing = "0x" + encoded.slice(2) + "00";
+     assert.throws(() => qc.decodeRlp(withTrailing), /trailing data/i);
+   });
+ 
+   it("encodeRlp supports null as empty bytes", () => {
+     const encoded = qc.encodeRlp(null);
+     assert.ok(typeof encoded === "string" && encoded.startsWith("0x"));
+     const decoded = qc.decodeRlp(encoded);
+     assert.equal(decoded, "0x");
+   });
+ });
+ 

package/test/unit/errors.test.js

@@ -0,0 +1,74 @@
+/**
+ * @testCategory unit
+ * @blockchainRequired false
+ * @transactional false
+ * @description Error helpers and error classes (direct coverage)
+ */
+ 
+ const { describe, it } = require("node:test");
+ const assert = require("node:assert/strict");
+ 
+ const qc = require("../../index");
+ 
+ describe("Errors", () => {
+   it("makeError sets code and shortMessage (info omitted vs null)", () => {
+     const e1 = qc.makeError("boom", "UNKNOWN_ERROR");
+     const e2 = qc.makeError("boom", "UNKNOWN_ERROR", null);
+ 
+     assert.equal(e1.code, "UNKNOWN_ERROR");
+     assert.equal(e1.shortMessage, "boom");
+     assert.equal(e2.code, "UNKNOWN_ERROR");
+     assert.equal(e2.shortMessage, "boom");
+   });
+ 
+   it("makeError attaches info and protects message/code/name", () => {
+    const e = qc.makeError("boom", "UNKNOWN_ERROR", { operation: "x" });
+     assert.equal(e.code, "UNKNOWN_ERROR");
+     assert.equal(e.shortMessage, "boom");
+     assert.equal(e.operation, "x");
+ 
+     assert.throws(() => qc.makeError("boom", "UNKNOWN_ERROR", { message: "nope" }));
+     assert.throws(() => qc.makeError("boom", "UNKNOWN_ERROR", { code: "NOPE" }));
+     assert.throws(() => qc.makeError("boom", "UNKNOWN_ERROR", { name: "Nope" }));
+    // shortMessage is defined read-only by makeError; passing it via info causes a TypeError
+    assert.throws(() => qc.makeError("boom", "UNKNOWN_ERROR", { shortMessage: "nope" }));
+   });
+ 
+   it("assert and assertArgument throw INVALID_ARGUMENT with metadata", () => {
+     assert.throws(
+       () => qc.assert(false, "bad", "INVALID_ARGUMENT", { operation: "test" }),
+       (err) => err && err.code === "INVALID_ARGUMENT" && String(err.message).includes("operation"),
+     );
+ 
+     assert.throws(
+       () => qc.assertArgument(false, "bad arg", "foo", 123),
+       (err) => err && err.code === "INVALID_ARGUMENT" && err.argument === "foo" && err.value === 123,
+     );
+   });
+ 
+   it("isError and isCallException match code", () => {
+     const err = qc.makeError("x", "CALL_EXCEPTION");
+     assert.equal(qc.isError(err, "CALL_EXCEPTION"), true);
+     assert.equal(qc.isCallException(err), true);
+     assert.equal(qc.isCallException(qc.makeError("x", "UNKNOWN_ERROR")), false);
+   });
+ 
+   it("ProviderError/TransactionError/ContractError set code and include info (info omitted vs null)", () => {
+     const p1 = new qc.ProviderError("p");
+     const p2 = new qc.ProviderError("p", null);
+     const p3 = new qc.ProviderError("p", { operation: "op" });
+     assert.equal(p1.code, "UNKNOWN_ERROR");
+     assert.equal(p1.shortMessage, "p");
+     assert.equal(p2.code, "UNKNOWN_ERROR");
+     assert.equal(p3.operation, "op");
+ 
+     const t1 = new qc.TransactionError("t", { reason: "r" });
+     assert.equal(t1.code, "UNKNOWN_ERROR");
+     assert.equal(t1.reason, "r");
+ 
+     const c1 = new qc.ContractError("c", { contract: "X" });
+     assert.equal(c1.code, "UNKNOWN_ERROR");
+     assert.equal(c1.contract, "X");
+   });
+ });
+ 

package/test/unit/filter-by-blockhash.test.js

@@ -0,0 +1,52 @@
+/**
+ * @testCategory unit
+ * @blockchainRequired false
+ * @transactional false
+ * @description FilterByBlockHash shape and getLogs forwarding
+ */
+
+const { describe, it } = require("node:test");
+const assert = require("node:assert/strict");
+
+const qc = require("../../index");
+
+describe("FilterByBlockHash", () => {
+  it("validates blockHash and normalizes it", () => {
+    assert.throws(() => new qc.FilterByBlockHash(null), (e) => e && e.code === "INVALID_ARGUMENT");
+    assert.throws(() => new qc.FilterByBlockHash("0x1234"), (e) => e && e.code === "INVALID_ARGUMENT"); // wrong length
+
+    const h = "0x" + "AA".repeat(32);
+    const f = new qc.FilterByBlockHash(h);
+    assert.equal(f.blockHash, "0x" + "aa".repeat(32));
+  });
+
+  it("is consumable by provider.getLogs (forwarded as eth_getLogs filter)", async () => {
+    class P extends qc.AbstractProvider {
+      constructor() {
+        super();
+        this.calls = [];
+      }
+      async _perform(method, params) {
+        this.calls.push({ method, params });
+        return [];
+      }
+    }
+
+    const p = new P();
+    const blockHash = "0x" + "11".repeat(32);
+    const address = "0x" + "22".repeat(32);
+    const topic0 = "0x" + "33".repeat(32);
+
+    const filter = new qc.FilterByBlockHash(blockHash, address, [topic0]);
+    const logs = await p.getLogs(filter);
+
+    assert.deepEqual(logs, []);
+    assert.equal(p.calls.length, 1);
+    assert.equal(p.calls[0].method, "eth_getLogs");
+    assert.equal(p.calls[0].params.length, 1);
+    assert.equal(p.calls[0].params[0].blockHash, blockHash);
+    assert.equal(p.calls[0].params[0].address, address);
+    assert.deepEqual(p.calls[0].params[0].topics, [topic0]);
+  });
+});
+

package/test/unit/generate-contract-cli.test.js

@@ -0,0 +1,39 @@
+/**
+ * @testCategory unit
+ * @blockchainRequired false
+ * @transactional false
+ * @description generate-sdk.js CLI help output
+ */
+
+const { describe, it } = require("node:test");
+const assert = require("node:assert/strict");
+const path = require("node:path");
+const { spawnSync } = require("node:child_process");
+
+describe("generate-sdk.js CLI", () => {
+  it("prints detailed help when invoked with no args", () => {
+    const repoRoot = path.resolve(__dirname, "..", "..");
+    const cli = path.join(repoRoot, "generate-sdk.js");
+
+    const res = spawnSync(process.execPath, [cli], {
+      cwd: repoRoot,
+      encoding: "utf8",
+      stdio: "pipe",
+      shell: false,
+      windowsHide: true,
+    });
+
+    assert.equal(res.status, 0);
+    const out = `${res.stdout || ""}${res.stderr || ""}`;
+    assert.ok(out.includes("quantumcoin-sdk-generator"));
+    assert.ok(out.includes("INPUT MODES"));
+    assert.ok(out.includes("--abi"));
+    assert.ok(out.includes("--bin"));
+    assert.ok(out.includes("--sol"));
+    assert.ok(out.includes("--artifacts-json"));
+    assert.ok(out.includes("--create-package"));
+    assert.ok(out.includes("--lang"));
+    assert.ok(out.includes("EXAMPLES"));
+  });
+});
+

package/test/unit/generate-sdk-artifacts-json.test.js

@@ -0,0 +1,110 @@
+/**
+ * @testCategory unit
+ * @blockchainRequired false
+ * @transactional false
+ * @description generate-sdk.js artifacts JSON input (multi-contract)
+ */
+
+const { describe, it } = require("node:test");
+const assert = require("node:assert/strict");
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const { spawnSync } = require("node:child_process");
+
+describe("generate-sdk.js --artifacts-json", () => {
+  it("generates typed files for multiple ABI+BIN pairs (no package scaffold)", () => {
+    const repoRoot = path.resolve(__dirname, "..", "..");
+    const cli = path.join(repoRoot, "generate-sdk.js");
+
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "qcgen-artjson-"));
+    const outDir = path.join(tmp, "out");
+
+    const alphaAbi = [
+      { type: "function", name: "get", stateMutability: "view", inputs: [], outputs: [{ name: "", type: "uint256" }] },
+    ];
+    const betaAbi = [
+      { type: "function", name: "set", stateMutability: "nonpayable", inputs: [{ name: "value", type: "uint256" }], outputs: [] },
+    ];
+    const gammaAbi = [
+      { type: "function", name: "ping", stateMutability: "pure", inputs: [], outputs: [{ name: "", type: "bool" }] },
+    ];
+
+    fs.writeFileSync(path.join(tmp, "Alpha.abi.json"), JSON.stringify(alphaAbi, null, 2), "utf8");
+    fs.writeFileSync(path.join(tmp, "Alpha.bin"), "0x6000", "utf8");
+    fs.writeFileSync(path.join(tmp, "Beta.abi.json"), JSON.stringify(betaAbi, null, 2), "utf8");
+    fs.writeFileSync(path.join(tmp, "Beta.bin"), "0x6000", "utf8");
+
+    const artifactsJsonPath = path.join(tmp, "artifacts.json");
+    fs.writeFileSync(
+      artifactsJsonPath,
+      JSON.stringify(
+        [
+          { abi: "./Alpha.abi.json", bin: "./Alpha.bin" },
+          { abi: "./Beta.abi.json", bin: "./Beta.bin" },
+          // Inline string form: abi is a JSON string; bin is inline bytecode (string).
+          { name: "Gamma", abi: JSON.stringify(gammaAbi), bin: "6000" },
+        ],
+        null,
+        2,
+      ),
+      "utf8",
+    );
+
+    const res = spawnSync(
+      process.execPath,
+      [cli, "--artifacts-json", artifactsJsonPath, "--out", outDir, "--non-interactive"],
+      { cwd: repoRoot, encoding: "utf8", stdio: "pipe", shell: false, windowsHide: true },
+    );
+
+    assert.equal(res.status, 0, `generator failed:\n${res.stdout}\n${res.stderr}`);
+
+    assert.ok(fs.existsSync(path.join(outDir, "types.ts")));
+    assert.ok(fs.existsSync(path.join(outDir, "index.ts")));
+    assert.ok(fs.existsSync(path.join(outDir, "Alpha.ts")));
+    assert.ok(fs.existsSync(path.join(outDir, "Alpha__factory.ts")));
+    assert.ok(fs.existsSync(path.join(outDir, "Beta.ts")));
+    assert.ok(fs.existsSync(path.join(outDir, "Beta__factory.ts")));
+    assert.ok(fs.existsSync(path.join(outDir, "Gamma.ts")));
+    assert.ok(fs.existsSync(path.join(outDir, "Gamma__factory.ts")));
+  });
+
+  it("supports --lang js (generates JS source + .d.ts types)", () => {
+    const repoRoot = path.resolve(__dirname, "..", "..");
+    const cli = path.join(repoRoot, "generate-sdk.js");
+
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "qcgen-artjson-js-"));
+    const outDir = path.join(tmp, "out");
+
+    const alphaAbi = [
+      { type: "function", name: "get", stateMutability: "view", inputs: [], outputs: [{ name: "", type: "uint256" }] },
+    ];
+    fs.writeFileSync(path.join(tmp, "Alpha.abi.json"), JSON.stringify(alphaAbi, null, 2), "utf8");
+    fs.writeFileSync(path.join(tmp, "Alpha.bin"), "0x6000", "utf8");
+
+    const artifactsJsonPath = path.join(tmp, "artifacts.json");
+    fs.writeFileSync(artifactsJsonPath, JSON.stringify([{ abi: "./Alpha.abi.json", bin: "./Alpha.bin" }], null, 2), "utf8");
+
+    const res = spawnSync(
+      process.execPath,
+      [cli, "--lang", "js", "--artifacts-json", artifactsJsonPath, "--out", outDir, "--non-interactive"],
+      { cwd: repoRoot, encoding: "utf8", stdio: "pipe", shell: false, windowsHide: true },
+    );
+
+    assert.equal(res.status, 0, `generator failed:\n${res.stdout}\n${res.stderr}`);
+
+    assert.ok(fs.existsSync(path.join(outDir, "types.js")));
+    assert.ok(fs.existsSync(path.join(outDir, "types.d.ts")));
+    assert.ok(fs.existsSync(path.join(outDir, "index.js")));
+    assert.ok(fs.existsSync(path.join(outDir, "index.d.ts")));
+    assert.ok(fs.existsSync(path.join(outDir, "Alpha.js")));
+    assert.ok(fs.existsSync(path.join(outDir, "Alpha.d.ts")));
+    assert.ok(fs.existsSync(path.join(outDir, "Alpha__factory.js")));
+    assert.ok(fs.existsSync(path.join(outDir, "Alpha__factory.d.ts")));
+
+    // Ensure generated types re-export core Solidity types (no local re-definition).
+    const typesDts = fs.readFileSync(path.join(outDir, "types.d.ts"), "utf8");
+    assert.ok(typesDts.includes('from "quantumcoin/types"'), "expected generated types.d.ts to reference quantumcoin/types");
+  });
+});
+

package/test/unit/generator.test.js

@@ -0,0 +1,98 @@
+/**
+ * @testCategory unit
+ * @blockchainRequired false
+ * @transactional false
+ * @description Typed contract generator (file output shape)
+ */
+
+const { describe, it } = require("node:test");
+const assert = require("node:assert/strict");
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+
+const { generate, generateFromArtifacts } = require("../../src/generator");
+
+describe("typed contract generator", () => {
+  it("generates contract + factory + types + index files", () => {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "qcgen-"));
+    const abiPath = path.join(tmp, "Test.abi.json");
+    const binPath = path.join(tmp, "Test.bin");
+    const outDir = path.join(tmp, "out");
+
+    const abi = [
+      {
+        type: "function",
+        name: "balanceOf",
+        stateMutability: "view",
+        inputs: [{ name: "account", type: "address" }],
+        outputs: [{ name: "", type: "uint256" }],
+      },
+      {
+        type: "function",
+        name: "transfer",
+        stateMutability: "nonpayable",
+        inputs: [
+          { name: "to", type: "address" },
+          { name: "amount", type: "uint256" },
+        ],
+        outputs: [{ name: "", type: "bool" }],
+      },
+    ];
+
+    fs.writeFileSync(abiPath, JSON.stringify(abi, null, 2), "utf8");
+    fs.writeFileSync(binPath, "0x6000", "utf8");
+
+    const res = generate({ abiPath, binPath, outDir, contractName: "TestToken" });
+    assert.ok(fs.existsSync(res.contractFile));
+    assert.ok(fs.existsSync(res.factoryFile));
+    assert.ok(fs.existsSync(res.typesFile));
+    assert.ok(fs.existsSync(res.indexFile));
+
+    const contractSrc = fs.readFileSync(res.contractFile, "utf8");
+    assert.ok(contractSrc.includes("export class TestToken"));
+    assert.ok(contractSrc.includes("async balanceOf"));
+    assert.ok(contractSrc.includes("async transfer"));
+
+    const factorySrc = fs.readFileSync(res.factoryFile, "utf8");
+    assert.ok(factorySrc.includes("export class TestToken__factory"));
+  });
+
+  it("includes injected docs in generated TypeScript", () => {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "qcgen-docs-"));
+    const outDir = path.join(tmp, "out");
+
+    const abi = [
+      {
+        type: "function",
+        name: "set",
+        stateMutability: "nonpayable",
+        inputs: [{ name: "value", type: "uint256" }],
+        outputs: [],
+      },
+    ];
+
+    const res = generateFromArtifacts({
+      outDir,
+      artifacts: [
+        {
+          contractName: "DocToken",
+          abi,
+          bytecode: "0x6000",
+          docs: {
+            contract: "Example contract doc from Solidity.",
+            functions: {
+              set: "Example function doc from Solidity.",
+            },
+          },
+        },
+      ],
+    });
+
+    const contractFile = res.contracts[0].contractFile;
+    const src = fs.readFileSync(contractFile, "utf8");
+    assert.ok(src.includes("Example contract doc from Solidity."));
+    assert.ok(src.includes("Example function doc from Solidity."));
+  });
+});
+

package/test/unit/hashing.test.js

@@ -0,0 +1,54 @@
+/**
+ * @testCategory unit
+ * @blockchainRequired false
+ * @transactional false
+ * @description Hashing helpers (optional params, deterministic behavior)
+ */
+ 
+ const { describe, it } = require("node:test");
+ const assert = require("node:assert/strict");
+ 
+ const qc = require("../../index");
+ 
+ describe("Hashing", () => {
+   it("keccak256 returns a 32-byte hex digest for empty bytes", () => {
+     const out = qc.keccak256(new Uint8Array([]));
+     assert.equal(typeof out, "string");
+     assert.ok(out.startsWith("0x"));
+     assert.equal(out.length, 66);
+   });
+ 
+   it("sha256/sha512/ripemd160 output lengths are correct", () => {
+     const data = qc.toUtf8Bytes("hello");
+     assert.equal(qc.sha256(data).length, 66);
+     assert.equal(qc.sha512(data).length, 130);
+     assert.equal(qc.ripemd160(data).length, 42);
+   });
+ 
+   it("randomBytes returns requested length", () => {
+     const b = qc.randomBytes(16);
+     assert.ok(b instanceof Uint8Array);
+     assert.equal(b.length, 16);
+   });
+ 
+   it("pbkdf2 algorithm defaults when omitted vs null vs explicit", () => {
+     const pw = qc.toUtf8Bytes("password");
+     const salt = qc.toUtf8Bytes("salt");
+ 
+     const a = qc.pbkdf2(pw, salt, 1, 32);
+     const b = qc.pbkdf2(pw, salt, 1, 32, "sha256");
+     const c = qc.pbkdf2(pw, salt, 1, 32, null);
+ 
+     assert.equal(a, b);
+     assert.equal(a, c);
+     assert.ok(a.startsWith("0x") && a.length === 66);
+   });
+ 
+   it("computeHmac produces a hex string", () => {
+     const key = qc.toUtf8Bytes("key");
+     const data = qc.toUtf8Bytes("data");
+     const out = qc.computeHmac("sha256", key, data);
+     assert.ok(typeof out === "string" && out.startsWith("0x") && out.length === 66);
+   });
+ });
+