@quantovainc/qcore 0.1.4 → 0.1.5

package/README.md

@@ -1,14 +1,56 @@
 # QCore.js
 
+[![ci](https://github.com/Quantova/QCore.js/actions/workflows/ci.yml/badge.svg)](https://github.com/Quantova/QCore.js/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/@quantovainc/qcore)](https://www.npmjs.com/package/@quantovainc/qcore)
+
+The post quantum client core for Quantova. It signs with ML-DSA-65, builds Q1 addresses, and runs the same compiled core in the browser and in Node.
+
 **This npm account and this package belong to Quantova Inc. It is the official Quantova client SDK. Any similarly named package published under a different account is not this one and is not from Quantova.**
 
-QCore.js is the official Quantova client core for JavaScript, built and published by Quantova Inc. The key derivation, the post quantum signing, and every RPC request body are handled by a single compiled core module and are never rewritten in JavaScript. The page does the fetch and the core does everything that has to be exactly right. That matters because a second implementation of the signing would be a second chance to be wrong with a user's money, so there is only ever the one.
+## Install
+
+```
+npm install @quantovainc/qcore
+```
+
+## Quickstart
+
+```js
+const { Client, core, generateSeed } = require('@quantovainc/qcore');
+
+async function main() {
+  // Create an account. The seed is the only backup and it never leaves the device.
+  const seed = generateSeed();
+  const phrase = core.mnemonicFromSeed(seed);
+
+  // Derive the Q1 address for account index zero, and a recipient at index one.
+  const from = core.address(seed, 0n);
+  const to = core.address(seed, 1n);
+  console.log('from', from);
+
+  // Open a client against a node you trust. Plaintext http is allowed only to a loopback node.
+  const client = new Client('http://127.0.0.1:8645');
 
-This is the official Quantova Inc package. On npm it installs as @quantovainc/qcore, which is the Quantova Inc account. Any package under a different scope or publisher, however close the name looks, is not this one and is not from Quantova.
+  // A fixed ceiling your app is willing to pay in fees, chosen here and never read back from the gateway.
+  const MAX_FEE_QUON = '2000';
+
+  // Amounts and the ceiling are decimal strings or BigInt values, never JavaScript numbers.
+  const { signed, outcome } = await client.transfer(seed, 0, to, '1000', MAX_FEE_QUON);
+  console.log('submitted', signed.tx_id, outcome.verdict);
+}
+
+main().catch((err) => { console.error(err.message); process.exit(1); });
+```
+
+A runnable copy of this lives in [examples/quickstart.js](examples/quickstart.js).
+
+## Security posture
+
+Every signature is ML-DSA-65 as standardised in FIPS 204, and addresses and transaction digests are built with SHA-3. There is no elliptic curve anywhere in this package, no secp256k1 and no ECDSA. When you send through the Client you pass a maximum fee that you choose yourself, and the Client refuses to sign when the gateway reports a fee above it, so a hostile gateway cannot inflate the fee and drain the balance. The Client also refuses an unsafe transport. A remote gateway must be reached over https, and plaintext http is allowed only to a loopback node, because a fee and a nonce read back over plaintext could be rewritten on the wire. This package is at the testnet and pre audit stage, so please do not read it as audited.
 
 ## What this library is for
 
-Any browser app, extension, or Node service that holds a Quantova account, reads the chain, and sends signed transactions. A wallet, a dApp, a block explorer front end, or a faucet page. Your code does the network fetch it prefers and QCore.js derives the key, signs the transaction, and builds the request body, so nothing about the cryptography or the byte layout of a transaction is written in JavaScript.
+Any browser app, extension, or Node service that holds a Quantova account, reads the chain, and sends signed transactions. A wallet, a dApp, a block explorer front end, or a faucet page. Your code does the network fetch it prefers and QCore.js derives the key, signs the transaction, and builds the request body, so nothing about the cryptography or the byte layout of a transaction is written in JavaScript. A second implementation of the signing would be a second chance to be wrong with a user's money, so there is only ever the one.
 
 ## The post quantum cryptography it handles
 
@@ -100,6 +142,10 @@ const signed = JSON.parse(
 
 The compiled core in this package is only the shipping form of the one Rust core, built so the same key derivation, signing, and wire code runs in a browser and in Node. It is not a virtual machine and it is not what the chain runs. The Quantova chain executes only the QVM, the container machine that runs contracts. The compiled core here is a client side build artifact and nothing more.
 
+## TypeScript
+
+The package ships TypeScript types in `index.d.ts`, so the Client, the core functions, and the Network helpers are all typed with no extra install.
+
 ## Builds
 
 The package ships one guarded surface, the Client with the fee cap and the amount guard, over two
@@ -115,17 +161,33 @@ and `@quantovainc/qcore/pkg-node` for the nodejs build. Those export only the co
 Client, no fee cap, and no amount guard, and are for an advanced caller who assembles the fee comparison
 alone. The default browser, import, node, and require resolutions never reach them.
 
-To build both from source.
+To build both from source, run the two documented builds or `npm run build`.
 
 ```
 wasm-pack build --target bundler --out-dir pkg
 wasm-pack build --target nodejs --out-dir pkg-node
 ```
 
-## A note on releases
+The offline test scripts run with `npm test`, and they need no network and no running gateway.
+
+## Conformance vectors
+
+The frozen conformance vectors live in the [conformance](conformance) folder of this repository. The address derivation is in `conformance/address.derivation.json`, the transfer in `conformance/transaction.transfer.json`, and the payable call in `conformance/transaction.payable.json`. The offline test `test-conformance.js` signs from these vectors and checks the binding matches them byte for byte, so a change that would move a signed transaction fails the test.
+
+## Examples
+
+The [examples](examples) folder holds a runnable quickstart that mirrors the one above. For fuller starters, see the Q-Scaffold and the Q-Forge repositories under the Quantova org, at https://github.com/Quantova/Q-Scaffold and https://github.com/Quantova/Q-Forge.
+
+## Releases and provenance
+
+Releases are published from CI by the publish workflow in `.github/workflows/publish.yml`, which runs on a pushed git tag. It builds the two wasm targets, runs the offline tests, and publishes with npm provenance, so the copy of the package on the registry carries a verified provenance badge that ties it to this exact public commit. Nothing is published to a registry without an explicit tag. This package handles a user's keys and a published version cannot be taken back.
+
+For the provenance publish to run, the maintainer adds an `NPM_TOKEN` automation secret to the repository, or configures npm trusted publishing for the package so the workflow authenticates over OIDC with no stored token.
+
+## Security
 
-Nothing here is published to a registry without an explicit release. This package handles a user's keys and a published version cannot be taken back.
+To report a vulnerability, see [SECURITY.md](SECURITY.md). Please report privately and not through a public issue.
 
 ## Ownership and license
 
-QCore.js is built and owned by Quantova Inc, and the signing lives in one compiled core and is never rewritten in JavaScript. It carries none of the industry stack and inherits nothing from it. It is released under the Apache 2.0 and MIT licenses so any wallet, explorer, or service may build on it, and the copyright stays with Quantova Inc.
+QCore.js is built and owned by Quantova Inc, and the signing lives in one compiled core and is never rewritten in JavaScript. It carries none of the industry stack and inherits nothing from it. It is dual licensed under the Apache 2.0 and MIT licenses so any wallet, explorer, or service may build on it, and the copyright stays with Quantova Inc.

package/index.d.ts

@@ -39,6 +39,7 @@ export interface QCore {
   address(seed_hex: string, index: bigint): string;
   block_by_height_body(height: bigint): string;
   buildSignedOrderCall(
+    chain_id: bigint,
     contract: string,
     selector_hex: string,
     scheme_off: bigint,

package/package.json

@@ -1,7 +1,11 @@
 {
   "name": "@quantovainc/qcore",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Quantova's post quantum client core for JavaScript. Signs with ML-DSA-65 and builds Q1 addresses.",
+  "scripts": {
+    "build": "wasm-pack build --target bundler --out-dir pkg && wasm-pack build --target nodejs --out-dir pkg-node",
+    "test": "node test-conformance.js && node test-sign-validate.js && node test-transport.js && node test-fee-cap.js"
+  },
   "keywords": [
     "post-quantum",
     "quantum-resistant",

package/pkg/package.json

@@ -2,7 +2,7 @@
   "name": "qcore-js",
   "type": "module",
   "description": "The JavaScript binding for the Quantova client core, generated over QCore with wasm-bindgen. The core does the key derivation, the post quantum signing, and the wire, the page does the fetch.",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "license": "Apache-2.0 OR MIT",
   "repository": {
     "type": "git",

package/pkg/qcore_js.d.ts

@@ -7,7 +7,7 @@ export function address(seed_hex: string, index: bigint): string;
 
 export function block_by_height_body(height: bigint): string;
 
-export function buildSignedOrderCall(contract: string, selector_hex: string, scheme_off: bigint, ptr_off: bigint, field_offs_csv: string, fields_csv: string, region_off: bigint, owner_seed_hex: string, owner_index: bigint, nonce: bigint): string;
+export function buildSignedOrderCall(chain_id: bigint, contract: string, selector_hex: string, scheme_off: bigint, ptr_off: bigint, field_offs_csv: string, fields_csv: string, region_off: bigint, owner_seed_hex: string, owner_index: bigint, nonce: bigint): string;
 
 export function chainIdFromName(name: string): bigint;
 

package/pkg/qcore_js_bg.js

@@ -61,6 +61,7 @@ export function block_by_height_body(height) {
 }
 
 /**
+ * @param {bigint} chain_id
  * @param {string} contract
  * @param {string} selector_hex
  * @param {bigint} scheme_off
@@ -73,7 +74,7 @@ export function block_by_height_body(height) {
  * @param {bigint} nonce
  * @returns {string}
  */
-export function buildSignedOrderCall(contract, selector_hex, scheme_off, ptr_off, field_offs_csv, fields_csv, region_off, owner_seed_hex, owner_index, nonce) {
+export function buildSignedOrderCall(chain_id, contract, selector_hex, scheme_off, ptr_off, field_offs_csv, fields_csv, region_off, owner_seed_hex, owner_index, nonce) {
     let deferred7_0;
     let deferred7_1;
     try {
@@ -87,7 +88,7 @@ export function buildSignedOrderCall(contract, selector_hex, scheme_off, ptr_off
         const len3 = WASM_VECTOR_LEN;
         const ptr4 = passStringToWasm0(owner_seed_hex, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
         const len4 = WASM_VECTOR_LEN;
-        const ret = wasm.buildSignedOrderCall(ptr0, len0, ptr1, len1, scheme_off, ptr_off, ptr2, len2, ptr3, len3, region_off, ptr4, len4, owner_index, nonce);
+        const ret = wasm.buildSignedOrderCall(chain_id, ptr0, len0, ptr1, len1, scheme_off, ptr_off, ptr2, len2, ptr3, len3, region_off, ptr4, len4, owner_index, nonce);
         var ptr6 = ret[0];
         var len6 = ret[1];
         if (ret[3]) {

package/pkg/qcore_js_bg.wasm.d.ts

@@ -4,7 +4,7 @@ export const memory: WebAssembly.Memory;
 export const account_body: (a: number, b: number) => [number, number];
 export const address: (a: number, b: number, c: bigint) => [number, number, number, number];
 export const block_by_height_body: (a: bigint) => [number, number];
-export const buildSignedOrderCall: (a: number, b: number, c: number, d: number, e: bigint, f: bigint, g: number, h: number, i: number, j: number, k: bigint, l: number, m: number, n: bigint, o: bigint) => [number, number, number, number];
+export const buildSignedOrderCall: (a: bigint, b: number, c: number, d: number, e: number, f: bigint, g: bigint, h: number, i: number, j: number, k: number, l: bigint, m: number, n: number, o: bigint, p: bigint) => [number, number, number, number];
 export const chainIdFromName: (a: number, b: number) => bigint;
 export const contractAddress: (a: number, b: number, c: bigint) => [number, number];
 export const eventsBody: (a: bigint) => [number, number];

package/pkg-node/package.json

@@ -1,7 +1,7 @@
 {
   "name": "qcore-js",
   "description": "The JavaScript binding for the Quantova client core, generated over QCore with wasm-bindgen. The core does the key derivation, the post quantum signing, and the wire, the page does the fetch.",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "license": "Apache-2.0 OR MIT",
   "repository": {
     "type": "git",

package/pkg-node/qcore_js.d.ts

@@ -7,7 +7,7 @@ export function address(seed_hex: string, index: bigint): string;
 
 export function block_by_height_body(height: bigint): string;
 
-export function buildSignedOrderCall(contract: string, selector_hex: string, scheme_off: bigint, ptr_off: bigint, field_offs_csv: string, fields_csv: string, region_off: bigint, owner_seed_hex: string, owner_index: bigint, nonce: bigint): string;
+export function buildSignedOrderCall(chain_id: bigint, contract: string, selector_hex: string, scheme_off: bigint, ptr_off: bigint, field_offs_csv: string, fields_csv: string, region_off: bigint, owner_seed_hex: string, owner_index: bigint, nonce: bigint): string;
 
 export function chainIdFromName(name: string): bigint;
 

package/pkg-node/qcore_js.js

@@ -66,6 +66,7 @@ function block_by_height_body(height) {
 exports.block_by_height_body = block_by_height_body;
 
 /**
+ * @param {bigint} chain_id
  * @param {string} contract
  * @param {string} selector_hex
  * @param {bigint} scheme_off
@@ -78,7 +79,7 @@ exports.block_by_height_body = block_by_height_body;
  * @param {bigint} nonce
  * @returns {string}
  */
-function buildSignedOrderCall(contract, selector_hex, scheme_off, ptr_off, field_offs_csv, fields_csv, region_off, owner_seed_hex, owner_index, nonce) {
+function buildSignedOrderCall(chain_id, contract, selector_hex, scheme_off, ptr_off, field_offs_csv, fields_csv, region_off, owner_seed_hex, owner_index, nonce) {
     let deferred7_0;
     let deferred7_1;
     try {
@@ -92,7 +93,7 @@ function buildSignedOrderCall(contract, selector_hex, scheme_off, ptr_off, field
         const len3 = WASM_VECTOR_LEN;
         const ptr4 = passStringToWasm0(owner_seed_hex, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
         const len4 = WASM_VECTOR_LEN;
-        const ret = wasm.buildSignedOrderCall(ptr0, len0, ptr1, len1, scheme_off, ptr_off, ptr2, len2, ptr3, len3, region_off, ptr4, len4, owner_index, nonce);
+        const ret = wasm.buildSignedOrderCall(chain_id, ptr0, len0, ptr1, len1, scheme_off, ptr_off, ptr2, len2, ptr3, len3, region_off, ptr4, len4, owner_index, nonce);
         var ptr6 = ret[0];
         var len6 = ret[1];
         if (ret[3]) {

package/shared.js

@@ -286,9 +286,18 @@ function makeClient(core) {
     async callSignedOrder(callerSeedHex, callerIndex, contract, selectorHex, layout, fields, ownerSeedHex, ownerIndex, meterLimit, maxFeeQuon) {
       if (!core.valid_address(contract)) throw new Error('the contract is not a q1 address');
       const ceiling = feeCeiling(maxFeeQuon);
+      const info = await this.nodeInfo();
+      this._guardMainnet();
+      const chainId = signingChainId(info);
+      const fee = info && info.fee && info.fee.transfer_quon;
+      if (fee == null) throw new Error('the gateway did not report a transfer fee');
+      if (BigInt(fee) > ceiling) {
+        throw new Error(`the gateway fee ${fee} is above the maximum you allowed ${maxFeeQuon}, refusing to sign`);
+      }
       const signer = core.orderSigner(ownerSeedHex, BigInt(ownerIndex));
       const nonce = await this.contractNonce(contract, signer);
       const order = JSON.parse(core.buildSignedOrderCall(
+        chainId,
         contract,
         selectorHex,
         BigInt(layout.schemeOff),
@@ -300,14 +309,6 @@ function makeClient(core) {
         BigInt(ownerIndex),
         nonce,
       ));
-      const info = await this.nodeInfo();
-      this._guardMainnet();
-      const chainId = signingChainId(info);
-      const fee = info && info.fee && info.fee.transfer_quon;
-      if (fee == null) throw new Error('the gateway did not report a transfer fee');
-      if (BigInt(fee) > ceiling) {
-        throw new Error(`the gateway fee ${fee} is above the maximum you allowed ${maxFeeQuon}, refusing to sign`);
-      }
       const from = core.address(callerSeedHex, BigInt(callerIndex));
       const acct = await this.account(from);
       if (!acct || acct.nonce == null) throw new Error('the gateway did not report a nonce');