quantumcoin 6.14.5 → 7.0.2

package/README.md

@@ -1,132 +1,152 @@
-# DRAFT: WORK IN PROGRESS : NOT READY FOR PRODUCTION YET
-
-The quantumcoin.js project
-===========================
-
-
-Initialize the SDK first before beginning to use it. Else you might run into unexpected errors.
-```
-import { ethers } from "quantumcoin";
-
-ethers.initQuantum().then((initResult) => {
-
-
-}
-```
-
------
-
-A complete, compact and simple library for Ethereum and ilk, written
-in [TypeScript](https://www.typescriptlang.org).
-
-**Features**
-
-- 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
-
-
-Keep Updated
-------------
-
-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.
-
-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).
-
-
-For the latest changes, see the
-[CHANGELOG](https://github.com/ethers-io/ethers.js/blob/main/CHANGELOG.md).
-
-
-Installing
-----------
-
-**NodeJS**
-
-```
-/home/ricmoo/some_project> npm install quantumcoin
-```
-
-**Browser (ESM)**
-
-The bundled library is available in the `./dist/` folder in this repo.
-
-```
-<script type="module">
-    import { ethers } from "./dist/quantumcoin.min.js";
-</script>
-```
-
-
-Documentation
--------------
-
-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/)
-
-
-
-Providers
----------
-
-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.
-
-These built-in keys mean you can use `ethers.getDefaultProvider()` and
-start developing right away.
-
-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.
-
-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.
-
-A special thanks to these services for providing community resources:
-
-- [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)
-
-
-Extension Packages
-------------------
-
-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.
-
-- [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
-
-
-License
--------
-
-MIT License (including **all** dependencies).
-
+<!--
+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, verifyMessage } = require("quantumcoin");
+const { Initialize } = require("quantumcoin/config");
+
+await Initialize(null);
+
+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);
+```
+
+## 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:
+
+`npx quantumcoin-sdk-generator --abi ... --bin ...`
+
+### 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.
+
+## 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
+```
+
+## 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`)
+
+