quantum-coin-js-sdk 1.0.36 → 1.0.39

package/example/node_modules/quantumcoin/README.md

@@ -0,0 +1,197 @@
+> **CAUTION:** This is an experimental SDK. Use at your own risk.
+
+**Comprehensive SDK documentation:** see [`README-SDK.md`](./README-SDK.md).
+
+## QuantumCoin.js
+
+QuantumCoin.js is an **ethers.js v6-compatible** SDK surface for the QuantumCoin blockchain.
+
+Key differences vs Ethereum/ethers:
+
+- **Addresses are 32 bytes** (66 hex chars including `0x`)
+- **No HDWallet support** (not applicable to QuantumCoin)
+- **All signing, address derivation, and ABI packing/unpacking** are delegated to `quantum-coin-js-sdk` (as required by `SPEC.md`)
+
+## Install
+
+```bash
+npm install quantumcoin
+```
+
+## Initialize (required)
+
+You **must** initialize once before using wallet/address/ABI helpers:
+
+```js
+const { Initialize, Config } = require("quantumcoin/config");
+
+// defaults: chainId=123123, rpcEndpoint=https://public.rpc.quantumcoinapi.com
+await Initialize(null);
+
+// or custom
+await Initialize(new Config(123123, "https://public.rpc.quantumcoinapi.com"));
+```
+
+## Provider (read-only)
+
+```js
+const { JsonRpcProvider } = require("quantumcoin");
+
+const provider = new JsonRpcProvider("https://public.rpc.quantumcoinapi.com", 123123);
+console.log(await provider.getBlockNumber());
+```
+
+## Wallet (offline + online)
+
+```js
+const { Wallet } = require("quantumcoin");
+const { Initialize } = require("quantumcoin/config");
+
+await Initialize(null);
+
+const wallet = Wallet.createRandom();
+
+const encrypted = wallet.encryptSync("mySecurePassword123");
+const restored = Wallet.fromEncryptedJsonSync(encrypted, "mySecurePassword123");
+console.log(restored.address);
+```
+
+### Seed phrase (`getPhrase()`)
+
+Any wallet that was constructed from a seed exposes its seed words via `getPhrase()`:
+
+```js
+const wallet = Wallet.createRandom();
+const phrase = wallet.getPhrase();      // string[] of seed words, or null
+const restored = Wallet.fromPhrase(phrase);
+console.log(restored.address === wallet.address); // true
+```
+
+`getPhrase()` returns the seed words whenever `wallet.seed` is non-null — i.e. wallets produced by `createRandom`, `fromPhrase`, `fromSeed`, or `fromEncryptedJsonSync` on a version-5 keystore (produced by `encryptSync` on a seed-bearing wallet or by `encryptSeedSync`). It returns `null` for wallets constructed via `fromKeys` or from v3/v4 keystores.
+
+### Encrypt a raw seed
+
+You can encrypt raw seed bytes (pre-expansion) into a portable wallet JSON (version 5 format) without first opening the wallet:
+
+```js
+const { Wallet } = require("quantumcoin");
+const { Initialize } = require("quantumcoin/config");
+
+await Initialize(null);
+
+// 64-byte seed (keyType 3), 72-byte (keyType 5), or 96-byte (legacy)
+const seed = [51,214,149,165, /* ...remaining bytes... */];
+const json = Wallet.encryptSeedSync(seed, "mySecurePassword123");
+const restored = Wallet.fromEncryptedJsonSync(json, "mySecurePassword123");
+console.log(restored.address);
+```
+
+## Contracts (read-only)
+
+```js
+const { Initialize } = require("quantumcoin/config");
+const { JsonRpcProvider, Contract } = require("quantumcoin");
+
+await Initialize(null);
+
+const provider = new JsonRpcProvider("https://public.rpc.quantumcoinapi.com", 123123);
+const abi = require("./test/fixtures/StakingContract.abi.json");
+const address = "0x0000000000000000000000000000000000000000000000000000000000001000";
+
+const staking = new Contract(address, abi, provider);
+console.log(await staking.getDepositorCount());
+```
+
+## Typed contract generator
+
+This repo includes a generator described in `SPEC.md` section 15.
+
+```bash
+# Non-interactive
+node generate-sdk.js --abi path/to/abi.json --bin path/to/bytecode.bin --out ./generated --name MyContract --non-interactive
+
+# JavaScript output (with TypeScript `.d.ts` types)
+node generate-sdk.js --lang js --abi path/to/abi.json --bin path/to/bytecode.bin --out ./generated --name MyContract --non-interactive
+
+# Interactive
+node generate-sdk.js --abi path/to/abi.json --bin path/to/bytecode.bin
+```
+
+If installed as a package, you can also run:
+
+```bash
+npx sdkgen --abi path/to/abi.json --bin path/to/bytecode.bin --out ./generated --name MyContract --non-interactive
+```
+
+For more options (Solidity sources, artifacts JSON, package scaffolding), see [README-SDK.md](./README-SDK.md#typed-sdk-generator-generate-sdkjs).
+
+### Generator typing model
+
+- **Hard types**: generated wrappers use concrete types from `quantumcoin/types` (e.g. `Uint256Like` for inputs, `Uint256` for outputs).
+- **Single return values are unwrapped**: a Solidity function returning one value returns that value directly (not `[value]`).
+- **Multiple returns**: returned as a tuple type (e.g. `Promise<[Uint256, Bool]>`).
+- **No returns**: `Promise<void>`.
+- **Structs / tuples**: generated as `export type <Name>Input` / `export type <Name>Output` and used directly in method signatures.
+
+### Interface contracts
+
+When the input artifact has empty bytecode (`"0x"` or empty `.bin`, typically produced by `solc` for a Solidity `interface`), the generator emits a transactional test that **skips the post-deploy bytecode check**. The deploy step still runs (the receipt-status assertion validates SDK wrapper wiring), but `provider.getCode(contract.target)` is not asserted to be non-empty — an interface deploys with no runtime code by design. Concrete contracts (non-empty bytecode) continue to assert that `provider.getCode(contract.target)` is non-empty.
+
+## Solidity types (TypeScript)
+
+QuantumCoin.js exports core Solidity-related typings from:
+
+- `quantumcoin/types`
+
+Common types:
+
+- `AddressLike` (currently `string`, 32-byte address)
+- `BytesLike` (`string | Uint8Array`)
+- `BigNumberish` (`string | number | bigint`)
+- **Hard Solidity aliases** (preferred for typed wrappers): `Uint256Like` / `Uint256`, `Int256Like` / `Int256`, `Bytes32Like` / `Bytes32`, and all widths `Uint8Like`…`Uint256Like`, `Int8Like`…`Int256Like`, plus `Bytes1Like`…`Bytes32Like`
+- `SolidityTypeName`, `SolidityInputValue<T>`, `SolidityOutputValue<T>` (advanced type-level mapping helpers; the generator no longer uses these for wrapper signatures)
+
+## Examples
+
+```bash
+npm run example
+npm run example:wallet
+npm run example:contract:read
+npm run example:events
+# Run all examples (including SDK generator JS/TS)
+npm run examples
+```
+
+To try the typed SDK generator (generates a full package from Solidity or ABI+BIN):
+
+```bash
+node examples/example-generator-sdk-js.js   # JavaScript output
+node examples/example-generator-sdk-ts.js   # TypeScript output
+```
+
+Requires `solc` on `QC_SOLC_PATH` or `SOLC_PATH`, or at default `c:\solc\solc.exe`. See [README-SDK.md](./README-SDK.md) for all generator options (`--artifacts-json`, `--sol`, `--create-package`, etc.).
+
+## Tests
+
+```bash
+npm test
+npm run test:unit
+npm run test:non-transactional
+npm run test:e2e
+```
+
+## Troubleshooting
+
+- **“SDK not initialized”**: call `Initialize(null)` once at startup.
+- **JSON-RPC errors/timeouts**: verify `Config.rpcEndpoint` or pass an explicit URL to `JsonRpcProvider`.
+- **Node version**: `quantum-coin-js-sdk` tooling is developed primarily against Node 20+. If you see runtime issues, try Node 20 LTS.
+
+### Transactional (write) tests
+
+The E2E tests broadcast real transactions and require a funded test wallet.
+
+- Set RPC URL via env var: `QC_RPC_URL`
+- (Optional) chain id via env var: `QC_CHAIN_ID` (default: 123123)
+- (Optional) solc path via env var: `QC_SOLC_PATH` (default: `c:\solc\solc.exe`)
+
+

package/example/node_modules/quantumcoin/config.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Configuration class for QuantumCoin SDK
+ * @class
+ */
+export class Config {
+    /**
+     * Creates a Config instance
+     * @param {number} chainId - The chain ID (default: 123123 for mainnet)
+     * @param {string} rpcEndpoint - The RPC endpoint URL (default: https://public.rpc.quantumcoinapi.com)
+     */
+    constructor(chainId?: number, rpcEndpoint?: string);
+    chainId: number;
+    rpcEndpoint: string;
+}
+/**
+ * Initializes the QuantumCoin SDK with the provided configuration.
+ *
+ * WARNING: This function MUST be called before using any SDK functionality.
+ * If Initialize() is not called, the SDK behavior can be unpredictable and
+ * may result in errors or incorrect validation results.
+ *
+ * If config is null or undefined, the SDK will be initialized with default values:
+ * - chainId: 123123 (mainnet)
+ * - rpcEndpoint: https://public.rpc.quantumcoinapi.com
+ *
+ * @param {Config|null} config - The configuration object containing chainId and rpcEndpoint.
+ *                                If null or undefined, default values will be used.
+ * @return {Promise<boolean>} Promise that resolves to true if initialization succeeded, false otherwise
+ * @example
+ * // Initialize with custom config
+ * const { Config, Initialize } = require('quantumcoin/config');
+ * const config = new Config(123123, 'https://rpc.example.com');
+ * await Initialize(config);
+ *
+ * @example
+ * // Initialize with default config (chainId: 123123, rpcEndpoint: https://public.rpc.quantumcoinapi.com)
+ * const { Initialize } = require('quantumcoin/config');
+ * await Initialize(null);
+ */
+export function Initialize(config: Config | null): Promise<boolean>;
+/**
+ * Checks if the SDK has been initialized
+ * @return {boolean} True if initialized, false otherwise
+ */
+export function isInitialized(): boolean;
+/**
+ * Returns the currently active SDK config (or null if not initialized).
+ * @return {Config|null}
+ */
+export function getConfig(): Config | null;

package/example/node_modules/quantumcoin/config.js

@@ -0,0 +1,123 @@
+/**
+ * Configuration class for QuantumCoin SDK
+ * 
+ * This module provides the Config class and Initialize function
+ * for setting up the QuantumCoin SDK.
+ * 
+ * @module config
+ */
+
+const qcsdk = require('quantum-coin-js-sdk');
+
+let _isInitialized = false;
+let _initializationPromise = null;
+let _config = null;
+
+// Default configuration values
+const DEFAULT_CHAIN_ID = 123123;
+const DEFAULT_RPC_ENDPOINT = "https://public.rpc.quantumcoinapi.com";
+const DEFAULT_READ_URL = "https://sdk.readrelay.quantumcoinapi.com";
+const DEFAULT_WRITE_URL = "https://sdk.writerelay.quantumcoinapi.com";
+
+/**
+ * Configuration class for QuantumCoin SDK
+ * @class
+ */
+class Config {
+    /**
+     * Creates a Config instance
+     * @param {number} chainId - The chain ID (default: 123123 for mainnet)
+     * @param {string} rpcEndpoint - The RPC endpoint URL (default: https://public.rpc.quantumcoinapi.com)
+     */
+    constructor(chainId = DEFAULT_CHAIN_ID, rpcEndpoint = DEFAULT_RPC_ENDPOINT) {
+        this.chainId = chainId;
+        this.rpcEndpoint = rpcEndpoint;
+    }
+}
+
+/**
+ * Initializes the QuantumCoin SDK with the provided configuration.
+ * 
+ * WARNING: This function MUST be called before using any SDK functionality.
+ * If Initialize() is not called, the SDK behavior can be unpredictable and
+ * may result in errors or incorrect validation results.
+ * 
+ * If config is null or undefined, the SDK will be initialized with default values:
+ * - chainId: 123123 (mainnet)
+ * - rpcEndpoint: https://public.rpc.quantumcoinapi.com
+ * 
+ * @param {Config|null} config - The configuration object containing chainId and rpcEndpoint.
+ *                                If null or undefined, default values will be used.
+ * @return {Promise<boolean>} Promise that resolves to true if initialization succeeded, false otherwise
+ * @example
+ * // Initialize with custom config
+ * const { Config, Initialize } = require('quantumcoin/config');
+ * const config = new Config(123123, 'https://rpc.example.com');
+ * await Initialize(config);
+ * 
+ * @example
+ * // Initialize with default config (chainId: 123123, rpcEndpoint: https://public.rpc.quantumcoinapi.com)
+ * const { Initialize } = require('quantumcoin/config');
+ * await Initialize(null);
+ */
+function Initialize(config) {
+    // If config is null or undefined, use default values
+    if (config === null || config === undefined) {
+        config = new Config(DEFAULT_CHAIN_ID, DEFAULT_RPC_ENDPOINT);
+    } else if (!(config instanceof Config)) {
+        throw new Error('Initialize() requires a Config instance as parameter, or null/undefined for default config');
+    }
+    
+    if (_initializationPromise === null) {
+        _config = config;
+
+        // Initialize quantum-coin-js-sdk (WASM + crypto helpers).
+        // Note: quantum-coin-js-sdk expects relay URLs for some network operations.
+        // We provide community defaults here; the ethers-compatible Provider uses `config.rpcEndpoint`.
+        const clientConfigVal = new qcsdk.Config(DEFAULT_READ_URL, DEFAULT_WRITE_URL, config.chainId, "", "");
+
+        _initializationPromise = qcsdk.initialize(clientConfigVal).then((initResult) => {
+            if (initResult === true) {
+                _isInitialized = true;
+            }
+            return initResult === true;
+        }).catch((error) => {
+            console.error('SDK initialization failed:', error);
+            return false;
+        });
+    }
+    
+    return _initializationPromise;
+}
+
+/**
+ * Checks if the SDK has been initialized
+ * @return {boolean} True if initialized, false otherwise
+ */
+function isInitialized() {
+    return _isInitialized;
+}
+
+/**
+ * Returns the currently active SDK config (or null if not initialized).
+ * @return {Config|null}
+ */
+function getConfig() {
+    return _config;
+}
+
+/**
+ * Returns the pending initialization promise, or null if Initialize() has not been called.
+ * @return {Promise<boolean>|null}
+ */
+function getInitializationPromise() {
+    return _initializationPromise;
+}
+
+module.exports = {
+    Config,
+    Initialize,
+    isInitialized,
+    getConfig,
+    getInitializationPromise
+};

package/example/node_modules/quantumcoin/examples/AllSolidityTypes.sol

@@ -0,0 +1,184 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.7.6;
+pragma experimental ABIEncoderV2;
+
+/// @title AllSolidityTypes
+/// @notice A Solidity 0.7.6 contract that exercises a wide surface of ABI-encodable types.
+/// @dev
+/// - Includes: bool, all int/uint widths, address/address payable, string, bytes, bytes1..bytes32
+/// - Includes: enums, nested structs, fixed/dynamic arrays, arrays of structs, structs of structs
+/// - Excludes: fixed-point types and function types (by request)
+/// - Note: mappings are not ABI-encodable, so they are shown only as a storage type.
+contract AllSolidityTypes {
+  enum Choice { None, One, Two }
+
+  // Mapping example (not ABI-encodable as param/return)
+  mapping(address => uint256) private _balances;
+
+  // --------------------------------------------------------------------------
+  // All integer widths
+  // --------------------------------------------------------------------------
+  struct AllUints {
+    uint8 u8; uint16 u16; uint24 u24; uint32 u32; uint40 u40; uint48 u48; uint56 u56; uint64 u64;
+    uint72 u72; uint80 u80; uint88 u88; uint96 u96; uint104 u104; uint112 u112; uint120 u120; uint128 u128;
+    uint136 u136; uint144 u144; uint152 u152; uint160 u160; uint168 u168; uint176 u176; uint184 u184; uint192 u192;
+    uint200 u200; uint208 u208; uint216 u216; uint224 u224; uint232 u232; uint240 u240; uint248 u248; uint256 u256;
+  }
+
+  struct AllInts {
+    int8 i8; int16 i16; int24 i24; int32 i32; int40 i40; int48 i48; int56 i56; int64 i64;
+    int72 i72; int80 i80; int88 i88; int96 i96; int104 i104; int112 i112; int120 i120; int128 i128;
+    int136 i136; int144 i144; int152 i152; int160 i160; int168 i168; int176 i176; int184 i184; int192 i192;
+    int200 i200; int208 i208; int216 i216; int224 i224; int232 i232; int240 i240; int248 i248; int256 i256;
+  }
+
+  // --------------------------------------------------------------------------
+  // All fixed-size bytes
+  // --------------------------------------------------------------------------
+  struct AllFixedBytes {
+    bytes1 b1; bytes2 b2; bytes3 b3; bytes4 b4; bytes5 b5; bytes6 b6; bytes7 b7; bytes8 b8;
+    bytes9 b9; bytes10 b10; bytes11 b11; bytes12 b12; bytes13 b13; bytes14 b14; bytes15 b15; bytes16 b16;
+    bytes17 b17; bytes18 b18; bytes19 b19; bytes20 b20; bytes21 b21; bytes22 b22; bytes23 b23; bytes24 b24;
+    bytes25 b25; bytes26 b26; bytes27 b27; bytes28 b28; bytes29 b29; bytes30 b30; bytes31 b31; bytes32 b32;
+  }
+
+  // --------------------------------------------------------------------------
+  // Misc ABI value types (plus arrays)
+  // --------------------------------------------------------------------------
+  struct AllMisc {
+    bool bo;
+    address addr;
+    address payable payableAddr;
+    string str;
+    bytes dynBytes;
+    Choice choice;
+    // Arrays of elementary types
+    uint256[] u256s;
+    int256[] i256s;
+    bytes32[] b32s;
+    address[] addrs;
+    bool[] bools;
+    string[] strings;
+    bytes[] bytesArr;
+    // Fixed arrays
+    uint16[3] fixedU16;
+    bytes32[2] fixedB32;
+  }
+
+  // Nested struct that contains structs and arrays of structs
+  struct Inner {
+    AllUints u;
+    AllInts i;
+    AllFixedBytes fb;
+    AllMisc misc;
+    // Array of structs
+    AllUints[] uStructs;
+    // Struct of structs
+    AllFixedBytes[2] fixedFb;
+    // Nested arrays
+    uint256[][] matrix;
+  }
+
+  struct Outer {
+    Inner inner;
+    Inner[] inners;        // dynamic array of structs
+    Inner[2] fixedInners;  // fixed array of structs
+    bytes32[][] b32Matrix;
+  }
+
+  AllUints private _storedU;
+  AllInts private _storedI;
+  AllFixedBytes private _storedFb;
+  AllMisc private _storedMisc;
+
+  /// @notice Constructor with multiple parameters (including structs and arrays).
+  constructor(
+    bool bo,
+    address payable payableAddr,
+    string memory str,
+    bytes memory dynBytes,
+    Choice choice,
+    AllUints memory u,
+    AllInts memory i,
+    AllFixedBytes memory fb,
+    AllMisc memory misc,
+    uint256[] memory seedU256s,
+    bytes32[2] memory seedB32
+  ) {
+    _storedU = u;
+    _storedI = i;
+    _storedFb = fb;
+
+    // Store some misc fields (keep it simple; not all array fields are persisted).
+    _storedMisc.bo = bo;
+    _storedMisc.addr = msg.sender;
+    _storedMisc.payableAddr = payableAddr;
+    _storedMisc.str = str;
+    _storedMisc.dynBytes = dynBytes;
+    _storedMisc.choice = choice;
+    _storedMisc.u256s = seedU256s;
+    _storedMisc.fixedB32 = seedB32;
+
+    // Touch mapping to demonstrate mapping existence.
+    _balances[msg.sender] = seedU256s.length;
+
+    // Use "misc" parameter to avoid unused warnings and ensure ABIEncoderV2 path is exercised.
+    if (misc.fixedU16.length > 0) {
+      _balances[misc.addr] = uint256(misc.fixedU16[0]);
+    }
+  }
+
+  // --------------------------------------------------------------------------
+  // Echo / roundtrip helpers (ABI-encodable inputs and outputs)
+  // --------------------------------------------------------------------------
+
+  function echoAllUints(AllUints memory x) external pure returns (AllUints memory) { return x; }
+  function echoAllInts(AllInts memory x) external pure returns (AllInts memory) { return x; }
+  function echoAllFixedBytes(AllFixedBytes memory x) external pure returns (AllFixedBytes memory) { return x; }
+  function echoAllMisc(AllMisc memory x) external pure returns (AllMisc memory) { return x; }
+
+  function echoInner(Inner memory x) external pure returns (Inner memory) { return x; }
+  function echoOuter(Outer memory x) external pure returns (Outer memory) { return x; }
+
+  // Arrays of structs and nested arrays
+  function echoAllUintsArray(AllUints[] memory xs) external pure returns (AllUints[] memory) { return xs; }
+  function echoInnerArray(Inner[] memory xs) external pure returns (Inner[] memory) { return xs; }
+  function echoMatrix(uint256[][] memory m) external pure returns (uint256[][] memory) { return m; }
+
+  // Multiple input params + multiple return params
+  function multiReturn(
+    bool bo,
+    address addr,
+    bytes32 b32,
+    string memory s,
+    uint256 x,
+    AllUints memory u
+  )
+    external
+    pure
+    returns (
+      bool outBo,
+      address outAddr,
+      address payable outPayableAddr,
+      bytes32 outB32,
+      string memory outS,
+      uint256 outX,
+      AllUints memory outU
+    )
+  {
+    outBo = bo;
+    outAddr = addr;
+    outPayableAddr = payable(addr);
+    outB32 = b32;
+    outS = s;
+    outX = x;
+    outU = u;
+  }
+
+  // Read-only getters to provide outputs without inputs
+  function getStoredUints() external view returns (AllUints memory) { return _storedU; }
+  function getStoredInts() external view returns (AllInts memory) { return _storedI; }
+  function getStoredFixedBytes() external view returns (AllFixedBytes memory) { return _storedFb; }
+  function getStoredMisc() external view returns (AllMisc memory) { return _storedMisc; }
+}
+

package/example/node_modules/quantumcoin/examples/SimpleIERC20.sol

@@ -0,0 +1,74 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.7.6;
+
+/// @title IERC20
+/// @notice Minimal ERC-20 interface (standard ABI surface).
+interface IERC20 {
+  event Transfer(address indexed from, address indexed to, uint256 value);
+  event Approval(address indexed owner, address indexed spender, uint256 value);
+
+  function totalSupply() external view returns (uint256);
+  function balanceOf(address account) external view returns (uint256);
+  function allowance(address owner, address spender) external view returns (uint256);
+
+  function transfer(address to, uint256 value) external returns (bool);
+  function approve(address spender, uint256 value) external returns (bool);
+  function transferFrom(address from, address to, uint256 value) external returns (bool);
+}
+
+/// @title SimpleERC20
+/// @notice A small deployable ERC-20 implementation for generator examples.
+contract SimpleERC20 is IERC20 {
+  string public name;
+  string public symbol;
+  uint8 public constant decimals = 18;
+
+  uint256 public override totalSupply;
+  mapping(address => uint256) public override balanceOf;
+  mapping(address => mapping(address => uint256)) public override allowance;
+
+  constructor(string memory _name, string memory _symbol, uint256 _initialSupply) {
+    name = _name;
+    symbol = _symbol;
+    _mint(msg.sender, _initialSupply);
+  }
+
+  function transfer(address to, uint256 value) external override returns (bool) {
+    _transfer(msg.sender, to, value);
+    return true;
+  }
+
+  function approve(address spender, uint256 value) external override returns (bool) {
+    allowance[msg.sender][spender] = value;
+    emit Approval(msg.sender, spender, value);
+    return true;
+  }
+
+  function transferFrom(address from, address to, uint256 value) external override returns (bool) {
+    uint256 allowed = allowance[from][msg.sender];
+    require(allowed >= value, "ALLOWANCE");
+    if (allowed != uint256(-1)) {
+      allowance[from][msg.sender] = allowed - value;
+      emit Approval(from, msg.sender, allowance[from][msg.sender]);
+    }
+    _transfer(from, to, value);
+    return true;
+  }
+
+  function _transfer(address from, address to, uint256 value) internal {
+    require(to != address(0), "TO_ZERO");
+    uint256 bal = balanceOf[from];
+    require(bal >= value, "BALANCE");
+    balanceOf[from] = bal - value;
+    balanceOf[to] += value;
+    emit Transfer(from, to, value);
+  }
+
+  function _mint(address to, uint256 value) internal {
+    require(to != address(0), "MINT_TO_ZERO");
+    totalSupply += value;
+    balanceOf[to] += value;
+    emit Transfer(address(0), to, value);
+  }
+}
+

package/example/node_modules/quantumcoin/examples/events.js

@@ -0,0 +1,41 @@
+/**
+ * Example: Querying logs/events (read-only).
+ * Run with VERBOSE=1 for addresses, block range, and log counts.
+ *
+ * Note: This is a simple log query example; it does not keep a live subscription
+ * running. For long-running subscriptions, build on Provider polling or a future
+ * WebSocketProvider implementation.
+ */
+
+const { Initialize } = require("../config");
+const { getProvider, Contract } = require("..");
+const { logExample, logAddress } = require("../test/verbose-logger");
+
+const RPC = "https://public.rpc.quantumcoinapi.com";
+const CHAIN_ID = 123123;
+const STAKING_CONTRACT = "0x" + "00".repeat(30) + "10" + "00"; // 0x...1000
+
+async function eventsExample() {
+  logExample("events.js", "starting", { rpc: RPC, chainId: CHAIN_ID });
+  await Initialize(null);
+
+  const provider = getProvider(RPC, CHAIN_ID);
+  logAddress("staking_contract", STAKING_CONTRACT);
+  const abi = require("../test/fixtures/StakingContract.abi.json");
+  const contract = new Contract(STAKING_CONTRACT, abi, provider);
+
+  // Query recent logs from the last 1000 blocks
+  const latest = await provider.getBlockNumber();
+  const fromBlock = Math.max(latest - 1000, 0);
+  logExample("events.js", "block range", { latest, fromBlock, toBlock: "latest" });
+
+  const logs = await contract.queryFilter("OnNewDeposit", fromBlock, "latest");
+  console.log(`Found ${logs.length} OnNewDeposit logs in last 1000 blocks`);
+  logExample("events.js", "queryFilter OnNewDeposit", { logCount: logs.length });
+}
+
+eventsExample().catch((e) => {
+  console.error(e);
+  process.exitCode = 1;
+});
+