quantumcoin 6.14.4 → 7.0.1

package/README.md

@@ -1,132 +1,127 @@
-# DRAFT: WORK IN PROGRESS : NOT READY FOR PRODUCTION YET
+<!--
+This is an experimental SDK. Use at your own risk.
+-->
 
-The quantumcoin.js project
-===========================
+**Comprehensive SDK documentation:** see [`README-SDK.md`](./README-SDK.md).
 
+## QuantumCoin.js
 
-Initialize the SDK first before beginning to use it. Else you might run into unexpected errors.
-```
-import { ethers } from "quantumcoin";
+QuantumCoin.js is an **ethers.js v6-compatible** SDK surface for the QuantumCoin blockchain.
 
-ethers.initQuantum().then((initResult) => {
+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
+```
 
-A complete, compact and simple library for Ethereum and ilk, written
-in [TypeScript](https://www.typescriptlang.org).
+## Initialize (required)
 
-**Features**
+You **must** initialize once before using wallet/address/ABI helpers:
 
-- Keep your private keys in your client, **safe** and sound
-- Import and export **JSON wallets** (Geth, Parity and crowdsale)
-- Import and export BIP 39 **mnemonic phrases** (12 word backup phrases) and **HD Wallets** (English as well as Czech, French, Italian, Japanese, Korean, Simplified Chinese, Spanish, Traditional Chinese)
-- Meta-classes create JavaScript objects from any contract ABI, including **ABIv2** and **Human-Readable ABI**
-- Connect to Ethereum nodes over [JSON-RPC](https://github.com/ethereum/wiki/wiki/JSON-RPC), [INFURA](https://infura.io), [Etherscan](https://etherscan.io), [Alchemy](https://alchemyapi.io), [Ankr](https://ankr.com) or [MetaMask](https://metamask.io)
-- **ENS names** are first-class citizens; they can be used anywhere an Ethereum addresses can be used
-- **Small** (~144kb compressed; 460kb uncompressed)
-- **Tree-shaking** focused; include only what you need during bundling
-- **Complete** functionality for all your Ethereum desires
-- Extensive [documentation](https://docs.ethers.org/v6/)
-- Large collection of **test cases** which are maintained and added to
-- Fully written in **TypeScript**, with strict types for security and safety
-- **MIT License** (including ALL dependencies); completely open source to do with as you please
+```js
+const { Initialize, Config } = require("quantumcoin/config");
 
+// defaults: chainId=123123, rpcEndpoint=https://public.rpc.quantumcoinapi.com
+await Initialize(null);
 
-Keep Updated
-------------
+// or custom
+await Initialize(new Config(123123, "https://public.rpc.quantumcoinapi.com"));
+```
 
-For advisories and important notices, follow [@ethersproject](https://twitter.com/ethersproject)
-on Twitter (low-traffic, non-marketing, important information only) as well as watch this GitHub project.
+## Provider (read-only)
 
-For more general news, discussions, and feedback, follow or DM me,
-[@ricmoo](https://twitter.com/ricmoo) on Twitter or on the
-[Ethers Discord](https://discord.gg/qYtSscGYYc).
+```js
+const { JsonRpcProvider } = require("quantumcoin");
 
+const provider = new JsonRpcProvider("https://public.rpc.quantumcoinapi.com", 123123);
+console.log(await provider.getBlockNumber());
+```
 
-For the latest changes, see the
-[CHANGELOG](https://github.com/ethers-io/ethers.js/blob/main/CHANGELOG.md).
+## Wallet (offline + online)
 
+```js
+const { Wallet, verifyMessage } = require("quantumcoin");
+const { Initialize } = require("quantumcoin/config");
 
-Installing
-----------
+await Initialize(null);
 
-**NodeJS**
+const wallet = Wallet.createRandom();
+const sig = wallet.signMessageSync("Hello, QuantumCoin!");
+console.log(verifyMessage("Hello, QuantumCoin!", sig));
 
+const encrypted = wallet.encryptSync("mySecurePassword123");
+const restored = Wallet.fromEncryptedJsonSync(encrypted, "mySecurePassword123");
+console.log(restored.address);
 ```
-/home/ricmoo/some_project> npm install quantumcoin
-```
-
-**Browser (ESM)**
 
-The bundled library is available in the `./dist/` folder in this repo.
+## Contracts (read-only)
 
-```
-<script type="module">
-    import { ethers } from "./dist/quantumcoin.min.js";
-</script>
-```
+```js
+const { Initialize } = require("quantumcoin/config");
+const { JsonRpcProvider, Contract } = require("quantumcoin");
 
+await Initialize(null);
 
-Documentation
--------------
+const provider = new JsonRpcProvider("https://public.rpc.quantumcoinapi.com", 123123);
+const abi = require("./test/fixtures/StakingContract.abi.json");
+const address = "0x0000000000000000000000000000000000000000000000000000000000001000";
 
-Browse the [documentation](https://docs.ethers.org) online:
-
-- [Getting Started](https://docs.ethers.org/v6/getting-started/)
-- [Full API Documentation](https://docs.ethers.org/v6/api/)
-- [Various Ethereum Articles](https://blog.ricmoo.com/)
+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.
 
-Providers
----------
+```bash
+# Non-interactive
+node generate-sdk.js --abi path/to/abi.json --bin path/to/bytecode.bin --out ./generated --name MyContract --non-interactive
 
-Ethers works closely with an ever-growing list of third-party providers
-to ensure getting started is quick and easy, by providing default keys
-to each service.
+# Interactive
+node generate-sdk.js --abi path/to/abi.json --bin path/to/bytecode.bin
+```
 
-These built-in keys mean you can use `ethers.getDefaultProvider()` and
-start developing right away.
+If installed as a package, you can also run:
 
-However, the API keys provided to ethers are also shared and are
-intentionally throttled to encourage developers to eventually get
-their own keys, which unlock many other features, such as faster
-responses, more capacity, analytics and other features like archival
-data.
+`npx quantumcoin-sdk-generator --abi ... --bin ...`
 
-When you are ready to sign up and start using for your own keys, please
-check out the [Provider API Keys](https://docs.ethers.org/v5/api-keys/) in
-the documentation.
+## Examples
 
-A special thanks to these services for providing community resources:
+```bash
+npm run example
+npm run example:wallet
+npm run example:contract:read
+npm run example:events
+```
 
-- [Ankr](https://www.ankr.com/)
-- [QuickNode](https://www.quicknode.com/)
-- [Etherscan](https://etherscan.io/)
-- [INFURA](https://infura.io/)
-- [Alchemy](https://dashboard.alchemyapi.io/signup?referral=55a35117-028e-4b7c-9e47-e275ad0acc6d)
+## Tests
 
+```bash
+npm test
+npm run test:unit
+npm run test:non-transactional
+npm run test:e2e
+```
 
-Extension Packages
-------------------
+## Troubleshooting
 
-The `ethers` package only includes the most common and most core
-functionality to interact with Ethereum. There are many other
-packages designed to further enhance the functionality and experience.
+- **“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.
 
-- [MulticallProvider](https://github.com/ethers-io/ext-provider-multicall) - A Provider which bundles multiple call requests into a single `call` to reduce latency and backend request capacity
-- [MulticoinPlugin](https://github.com/ethers-io/ext-provider-plugin-multicoin) - A Provider plugin to expand the support of ENS coin types
-- [GanaceProvider](https://github.com/ethers-io/ext-provider-ganache) - A Provider for in-memory node instances, for fast debugging, testing and simulating blockchain operations
-- [Optimism Utilities](https://github.com/ethers-io/ext-utils-optimism) - A collection of Optimism utilities
-- [LedgerSigner](https://github.com/ethers-io/ext-signer-ledger) - A Signer to interact directly with Ledger Hardware Wallets
+### Transactional (write) tests
 
+The E2E tests broadcast real transactions and require a funded test wallet.
 
-License
--------
+- 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`)
 
-MIT License (including **all** dependencies).
 

package/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/config.js

@@ -0,0 +1,115 @@
+/**
+ * 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;
+}
+
+// Export Config class and Initialize function
+module.exports = {
+    Config,
+    Initialize,
+    isInitialized,
+    getConfig
+};

package/examples/events.js

@@ -0,0 +1,35 @@
+/**
+ * Example: Querying logs/events (read-only).
+ *
+ * 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 { JsonRpcProvider, Contract } = require("..");
+
+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() {
+  await Initialize(null);
+
+  const provider = new JsonRpcProvider(RPC, CHAIN_ID);
+  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);
+
+  const logs = await contract.queryFilter("OnNewDeposit", fromBlock, "latest");
+  console.log(`Found ${logs.length} OnNewDeposit logs in last 1000 blocks`);
+}
+
+eventsExample().catch((e) => {
+  console.error(e);
+  process.exitCode = 1;
+});
+

package/examples/example.js

@@ -0,0 +1,61 @@
+/**
+ * QuantumCoin.js Examples (non-transactional).
+ *
+ * Run:
+ * - `node examples/example.js`
+ *
+ * These examples only perform:
+ * - SDK initialization
+ * - Read-only JSON-RPC queries
+ * - Offline wallet operations (sign/encrypt)
+ * - Read-only contract call against the system staking contract
+ */
+
+const { Initialize } = require("../config");
+const qc = require("..");
+
+const RPC = "https://public.rpc.quantumcoinapi.com";
+const CHAIN_ID = 123123;
+const STAKING_CONTRACT = "0x" + "00".repeat(30) + "10" + "00"; // 0x...1000
+
+async function main() {
+  const ok = await Initialize(null);
+  if (!ok) throw new Error("Initialize failed");
+
+  console.log("SDK initialized:", qc.isInitialized());
+
+  // Provider: basic read-only calls
+  const provider = new qc.JsonRpcProvider(RPC, CHAIN_ID);
+  const blockNumber = await provider.getBlockNumber();
+  console.log("Latest block:", blockNumber);
+
+  const block = await provider.getBlock("latest");
+  console.log("Latest block hash:", block.hash);
+
+  const balance = await provider.getBalance(STAKING_CONTRACT);
+  console.log("Staking contract balance (wei):", balance.toString());
+
+  // Wallet: offline operations
+  const wallet = qc.Wallet.createRandom();
+  console.log("Random wallet address:", wallet.address);
+  const sig = wallet.signMessageSync("Hello, QuantumCoin!");
+  console.log("Signed message signature:", sig.slice(0, 18) + "...");
+  const recovered = qc.verifyMessage("Hello, QuantumCoin!", sig);
+  console.log("Recovered address:", recovered);
+
+  const encrypted = wallet.encryptSync("mySecurePassword123");
+  console.log("Encrypted wallet JSON length:", encrypted.length);
+
+  // Contract: read-only call
+  const abi = require("../test/fixtures/StakingContract.abi.json");
+  const staking = new qc.Contract(STAKING_CONTRACT, abi, provider);
+  const depositorCount = await staking.getDepositorCount();
+  const count = Array.isArray(depositorCount) ? depositorCount[0] : depositorCount;
+  console.log("Depositor count:", String(count));
+}
+
+main().catch((e) => {
+  console.error(e);
+  process.exitCode = 1;
+});
+