quantumcoin 7.0.1 → 7.0.3

package/.gitignore

@@ -1,6 +1,9 @@
 node_modules/**
 output/**
 examples/node_modules/**
+examples/example-generated-sdk-ts/**
+examples/example-generated-sdk-js/**
+test/e2e/generated-sdks/**
 **/*.save
 **/*.swp
 **/*.tgz

package/README-SDK.md

@@ -1,6 +1,4 @@
-<!--
-This is an experimental SDK. Use at your own risk.
--->
+> **CAUTION:** This is an experimental SDK. Use at your own risk.
 
 # QuantumCoin.js — Comprehensive SDK Documentation
 
@@ -563,6 +561,35 @@ From `quantumcoin`:
 **Example(s):**
 - `examples/wallet-offline.js`
 
+## Solidity Types (TypeScript)
+
+QuantumCoin.js exposes core Solidity-related types for TypeScript users.
+
+- **Import path**: `quantumcoin/types`
+
+**Key exports**
+
+- `AddressLike` (currently `string`, 32-byte address)
+- `BytesLike` (`string | Uint8Array`)
+- `BigNumberish` (`string | number | bigint`)
+- `SolidityTypeName` (ABI type string model)
+- **Hard Solidity aliases** (preferred for typed wrappers):
+  - Integers: `Uint256Like` / `Uint256`, `Int256Like` / `Int256` (and all widths `Uint8Like`…`Uint256Like`, `Int8Like`…`Int256Like`)
+  - Fixed bytes: `Bytes32Like` / `Bytes32` (and `Bytes1Like`…`Bytes32Like`)
+  - Arrays/tuples helpers: `SolArray<T>`, `SolFixedArray<T, N>`, `SolStruct<T>`
+- `SolidityInputValue<T>` / `SolidityOutputValue<T>` (advanced type-level mapping from ABI type strings to JS values; the generator no longer uses these for wrapper signatures)
+
+Example:
+
+```ts
+import type { AddressLike, BigNumberish, Uint256Like, Uint256 } from "quantumcoin/types";
+
+const to: AddressLike = "0x0000000000000000000000000000000000000000000000000000000000001000";
+const amount: BigNumberish = "123";
+const asInput: Uint256Like = amount;
+const asOutput: Uint256 = 123n;
+```
+
 ### Encoding utilities
 
 - `toUtf8String(data: BytesLike): string`
@@ -625,11 +652,24 @@ From `quantumcoin`:
 
 ### Overview
 
-`generate-sdk.js` creates **typed TypeScript wrappers** for one or more contracts, and can optionally scaffold a complete npm package (with examples and transactional tests).
+`generate-sdk.js` creates **typed contract wrappers** for one or more contracts, and can optionally scaffold a complete npm package (with examples and transactional tests).
+
+It supports generating:
+- **TypeScript source** (`--lang ts`, default)
+- **JavaScript source + TypeScript declarations** (`--lang js`)
+
+**Typing behaviour (generated wrappers)**
+
+- **Hard types**: wrapper signatures use concrete types from `quantumcoin/types` (e.g. `Uint256Like` for inputs, `Uint256` for outputs).
+- **Single output unwrapping**: functions returning one value return the value directly (not `[value]`).
+- **Multiple outputs**: returned as a tuple type (e.g. `Promise<[Uint256, Bool]>`).
+- **No outputs**: `Promise<void>`.
+- **Structs / tuples**: emitted as `export type <Name>Input` / `export type <Name>Output` and used in signatures.
+- **JS typing**: JS output uses JSDoc types plus `.d.ts` files; TS users still get strong types.
 
 **Entry point**
 - `node generate-sdk.js ...`
-- or `npx quantumcoin-sdk-generator ...` (when installed)
+- or `npx sdkgen ...` (when installed)
 
 ### Input modes
 
@@ -637,12 +677,18 @@ From `quantumcoin`:
 
 ```bash
 node generate-sdk.js --abi path/to/My.abi.json --bin path/to/My.bin --name MyContract --out ./out --non-interactive
+
+# JS output
+node generate-sdk.js --lang js --abi path/to/My.abi.json --bin path/to/My.bin --name MyContract --out ./out --non-interactive
 ```
 
 2) **Solidity sources**
 
 ```bash
 node generate-sdk.js --sol ".\\contracts\\A.sol,.\\contracts\\B.sol" --solc "c:\\solc\\solc.exe" --out ./out --non-interactive
+
+# Pass additional solc args (example)
+node generate-sdk.js --sol ".\\contracts\\A.sol" --solc "c:\\solc\\solc.exe" --solc-args "--via-ir --evm-version london" --out ./out --non-interactive
 ```
 
 3) **Artifacts JSON (multi-contract ABI+BIN list)**
@@ -656,16 +702,22 @@ Example `artifacts.json`:
 ```json
 [
   { "abi": "./Alpha.abi.json", "bin": "./Alpha.bin" },
-  { "abi": "./Beta.abi.json", "bin": "./Beta.bin", "name": "Beta" }
+  { "abi": "./Beta.abi.json", "bin": "./Beta.bin", "name": "Beta" },
+  {
+    "name": "Gamma",
+    "abi": "[{\"type\":\"function\",\"name\":\"set\",\"stateMutability\":\"nonpayable\",\"inputs\":[{\"name\":\"value\",\"type\":\"uint256\"}],\"outputs\":[]}]",
+    "bin": "0x6000600055..."
+  }
 ]
 ```
 
 ### Package scaffolding mode
 
-Use `--create-package` to create a full npm package (source, tests, examples, README build scripts).
+Use `--create-package` to create a full npm package (source, tests, examples, README).
 
 ```bash
 node generate-sdk.js --artifacts-json .\\artifacts.json ^
+  --lang ts ^
   --create-package --package-dir .\\tmp --package-name my-typed-package ^
   --package-description "My typed package" --package-author "me" ^
   --package-license MIT --package-version 0.0.1 ^
@@ -676,11 +728,13 @@ node generate-sdk.js --artifacts-json .\\artifacts.json ^
 
 When `--create-package` is used, the generator produces:
 
-- `src/` typed contract wrappers + factories + `types.ts`
+- `src/` contract wrappers + factories
+  - TS mode: `*.ts` (compiled output in `dist/` after `npm run build:ts`)
+  - JS mode: `*.js` with `*.d.ts` types (no build step required)
 - `test/e2e/*.e2e.test.js` per-contract transactional tests
 - `examples/` deploy/read/write/events scripts
-- `index.js` (JSDoc source for `jsdoc-to-markdown`)
-- `README.md`, `index.d.ts` produced by `npm run build*`
+- `README.md` generated by the generator (includes ABI-derived API overview)
+- `index.js` + `index.d.ts` (package entry shims)
 
 ### Running generated transactional tests
 

package/README.md

@@ -1,6 +1,4 @@
-<!--
-This is an experimental SDK. Use at your own risk.
--->
+> **CAUTION:** This is an experimental SDK. Use at your own risk.
 
 **Comprehensive SDK documentation:** see [`README-SDK.md`](./README-SDK.md).
 
@@ -84,13 +82,38 @@ This repo includes a generator described in `SPEC.md` section 15.
 # 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 ...`
+`npx sdkgen --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