@quantovainc/qcore 0.2.0 → 0.2.2

package/README.md

@@ -16,7 +16,7 @@ npm install @quantovainc/qcore
 ## Quickstart
 
 ```js
-const { Client, core, generateSeed } = require('@quantovainc/qcore');
+const { Client, Network, core, generateSeed } = require('@quantovainc/qcore');
 
 const GATEWAY = 'https://rpc-testnet.quantova.org';
 
@@ -32,7 +32,7 @@ async function main() {
 
   // Open a client against a node you trust. The address above is the public testnet
   // gateway. A remote gateway must be https, plaintext http is allowed only to a loopback node.
-  const client = new Client(GATEWAY);
+  const client = new Client(GATEWAY, { network: Network.testnet() });
 
   // 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';
@@ -108,6 +108,11 @@ const seed = generateSeed();                 // thirty two random bytes as hex f
 const phrase = core.mnemonicFromSeed(seed);  // the only backup, shown once and kept on the device
 ```
 
+`core.seedFromMnemonic(phrase)` restores the seed from the twenty four words. It ignores case and extra
+spacing and applies Unicode NFKD before it looks a word up, so a phrase pasted with capitals, non breaking
+spaces, or full width letters restores the same seed. A standard BIP-39 phrase from another wallet is
+refused with its own error, since a Quantova phrase carries a SHA3 checksum and cannot be restored from it.
+
 ## Using it
 
 The last argument to a Client signing call, transfer, register, call, or callSignedOrder, is a fee
@@ -122,9 +127,23 @@ same reason as the amount, because a number silently rounds above 2^53 and could
 than you intended.
 
 This comparison lives in the Client and only in the Client. The raw core.* signing functions, such as
-core.sign_transfer, take the actual fee that goes on the wire as their last argument, not a ceiling, and
-do no gateway comparison at all. A developer who calls core.* directly has no fee cap, so reach for the
-Client whenever a gateway you do not control reports the fee.
+core.sign_transfer, take the actual fee that goes on the wire, not a ceiling, and do no gateway
+comparison at all. A developer who calls core.* directly has no fee cap, so reach for the Client whenever
+a gateway you do not control reports the fee.
+
+A contract call pays one transfer fee for every started 1210 units of its meter limit, and the chain
+refuses a call that pays less. The raw call signers, core.sign_call, core.signPayableCall, and
+core.signAssetCall, take the transfer fee the gateway reports as their last argument and refuse to sign a
+fee below `vmCallFee(transferFee, meterLimit)`, a meter limit outside 1210 to 12500000, or call arguments
+above 128 KiB. Every raw signer also refuses a validity deadline of zero, which would never expire, and
+core.sign_transfer refuses a transfer to the sending account itself. Numbers passed to core.* are decimal
+digit strings, non negative BigInt values, or non negative safe integers, and anything else is refused
+before the seed reaches the compiled core.
+
+A Client opened for a plain url with no network signs only for a private chain. It refuses the public
+testnet and any `Q-main-net-` chain until you name the network, with `Network.testnet()`, a mainnet
+network and `acknowledgeMainnet: true`, or `expectedChainId`. An expected nonce you pass must be the
+nonce the gateway reports, because the chain admits only the next nonce of an account.
 
 ```js
 const { Client, generateSeed } = require('@quantovainc/qcore');
@@ -157,13 +176,18 @@ await client.register(seed, 0, MAX_FEE_QUON);
 A call that also moves value, such as a payable contract call, reaches for `core.signPayableCall`
 directly. It takes the value and the chain id as explicit arguments, the value as a decimal string or a
 BigInt for the same reason as an amount, and the chain id from `core.localChainId()`,
-`core.mainnetChainId()`, or `core.testnetChainId()` so the network is never a magic number.
+`core.mainnetChainId()`, or `core.testnetChainId()` so the network is never a magic number. It also
+takes the validity deadline, the height after which the chain drops the transaction, from `validUntil`,
+and the transfer fee the gateway reports so the call fee can be checked against the meter limit.
 
 ```js
-const { core } = require('@quantovainc/qcore');
+const { core, validUntil, vmCallFee } = require('@quantovainc/qcore');
 
+const info = await client.nodeInfo();
+const transferFee = info.fee.transfer_quon;
+const fee = vmCallFee(transferFee, meterLimit);
 const signed = JSON.parse(
-  core.signPayableCall(seed, 0n, contract, argsHex, nonce, meterLimit, fee, '1000', core.testnetChainId()),
+  core.signPayableCall(seed, 0n, contract, argsHex, nonce, meterLimit, fee, '1000', core.testnetChainId(), validUntil(info), transferFee),
 );
 ```
 
@@ -197,7 +221,7 @@ The offline test scripts run with `npm test`, and they need no network and no ru
 
 ## 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.
+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 frozen transactions were signed with a validity deadline of zero, which the binding now refuses, so each transaction vector also carries a `bounded` companion signed at a real deadline. The offline test `test-conformance.js` signs from these vectors, checks the binding matches the bounded transaction byte for byte, and checks its body is the frozen body with only the deadline moved, so a change that would move a signed transaction fails the test.
 
 ## Examples
 

package/browser.mjs

@@ -1,9 +1,11 @@
 // Copyright 2026 Quantova Inc
 // SPDX-License-Identifier: Apache-2.0 OR MIT
 
-import * as core from './pkg/qcore_js.js';
-import { makeClient, generateSeed, validUntil, Network } from './shared.mjs';
+import * as raw from './pkg/qcore_js.js';
+import { makeClient, wrapCore, generateSeed, validUntil, Network } from './shared.mjs';
 
+const core = wrapCore(raw);
 const Client = makeClient(core);
+const vmCallFee = core.vmCallFee;
 
-export { Client, core, generateSeed, validUntil, Network };
+export { Client, core, generateSeed, validUntil, vmCallFee, Network };

package/index.d.ts

@@ -47,106 +47,113 @@ export interface SignedOrderResult {
   outcome: any;
 }
 
+export type WholeNumber = bigint | number | string;
+
 export interface QCore {
   account_body(address: string): string;
-  address(seed_hex: string, index: bigint): string;
-  block_by_height_body(height: bigint): string;
+  address(seed_hex: string, index: WholeNumber): string;
+  block_by_height_body(height: WholeNumber): string;
   buildSignedOrderCall(
-    chain_id: bigint,
+    chain_id: WholeNumber,
     contract: string,
     selector_hex: string,
-    scheme_off: bigint,
-    ptr_off: bigint,
+    scheme_off: WholeNumber,
+    ptr_off: WholeNumber,
     field_offs_csv: string,
     fields_csv: string,
-    region_off: bigint,
+    region_off: WholeNumber,
     owner_seed_hex: string,
-    owner_index: bigint,
-    nonce: bigint,
+    owner_index: WholeNumber,
+    nonce: WholeNumber,
   ): string;
   buildTypedOrderCall(
-    chain_id: bigint,
+    chain_id: WholeNumber,
     contract: string,
     selector_hex: string,
-    scheme_off: bigint,
-    ptr_off: bigint,
-    region_off: bigint,
+    scheme_off: WholeNumber,
+    ptr_off: WholeNumber,
+    region_off: WholeNumber,
     fields_json: string,
     owner_seed_hex: string,
-    owner_index: bigint,
-    nonce: bigint,
+    owner_index: WholeNumber,
+    nonce: WholeNumber,
   ): string;
-  contractAddress(deployer: string, nonce: bigint): string | undefined;
+  checkValidUntil(valid_until: WholeNumber, head: WholeNumber): void;
+  contractAddress(deployer: string, nonce: WholeNumber): string | undefined;
   chainIdFromName(name: string): bigint;
-  eventsBody(height: bigint): string;
+  eventsBody(height: WholeNumber): string;
   localChainId(): bigint;
   mainnetChainId(): bigint;
-  mapSlotKey(map_domain_tag: bigint, key_address_hex: string): string;
+  mapAddrWordKey(map_domain_tag: WholeNumber, key32_hex: string, word: WholeNumber): string;
+  mapSlotKey(map_domain_tag: WholeNumber, key_address_hex: string): string;
   mnemonicFromSeed(seed_hex: string): string;
   nonceSlotKey(signer_hex: string): string;
-  orderSigner(seed_hex: string, index: bigint): string;
+  orderSigner(seed_hex: string, index: WholeNumber): string;
   parseEvents(response: string): string;
-  scalarSlotKey(slot: bigint): string;
+  scalarSlotKey(slot: WholeNumber): string;
   tokenDecimalsSlot(): bigint;
   tokenSymbolSlot(): bigint;
   packSymbol(symbol: string): bigint;
-  unpackSymbol(word: bigint): string;
+  unpackSymbol(word: WholeNumber): string;
   assetBalanceBody(issuer: string, holder: string): string;
   assetSupplyBody(issuer: string): string;
   seedFromMnemonic(phrase: string): string;
   signPayableCall(
     seed_hex: string,
-    index: bigint,
+    index: WholeNumber,
     target: string,
     args_hex: string,
-    nonce: bigint,
-    meter_limit: bigint,
-    fee: string,
-    value: string,
-    chain_id: bigint,
-    valid_until: bigint,
+    nonce: WholeNumber,
+    meter_limit: WholeNumber,
+    fee: WholeNumber,
+    value: WholeNumber,
+    chain_id: WholeNumber,
+    valid_until: WholeNumber,
+    transfer_fee: WholeNumber,
   ): string;
   signAssetCall(
     seed_hex: string,
-    index: bigint,
+    index: WholeNumber,
     target: string,
     args_hex: string,
     asset_issuer: string,
-    amount: string,
-    nonce: bigint,
-    meter_limit: bigint,
-    fee: string,
-    chain_id: bigint,
-    valid_until: bigint,
+    amount: WholeNumber,
+    nonce: WholeNumber,
+    meter_limit: WholeNumber,
+    fee: WholeNumber,
+    chain_id: WholeNumber,
+    valid_until: WholeNumber,
+    transfer_fee: WholeNumber,
   ): string;
   signRegister(
     seed_hex: string,
-    index: bigint,
-    nonce: bigint,
-    fee: string,
-    chain_id: bigint,
-    valid_until: bigint,
+    index: WholeNumber,
+    nonce: WholeNumber,
+    fee: WholeNumber,
+    chain_id: WholeNumber,
+    valid_until: WholeNumber,
   ): string;
   sign_call(
     seed_hex: string,
-    index: bigint,
+    index: WholeNumber,
     target: string,
     args_hex: string,
-    nonce: bigint,
-    meter_limit: bigint,
-    fee: string,
-    chain_id: bigint,
-    valid_until: bigint,
+    nonce: WholeNumber,
+    meter_limit: WholeNumber,
+    fee: WholeNumber,
+    chain_id: WholeNumber,
+    valid_until: WholeNumber,
+    transfer_fee: WholeNumber,
   ): string;
   sign_transfer(
     seed_hex: string,
-    index: bigint,
+    index: WholeNumber,
     to: string,
-    amount: string,
-    nonce: bigint,
-    fee: string,
-    chain_id: bigint,
-    valid_until: bigint,
+    amount: WholeNumber,
+    nonce: WholeNumber,
+    fee: WholeNumber,
+    chain_id: WholeNumber,
+    valid_until: WholeNumber,
   ): string;
   storageBody(contract: string): string;
   storageValue(response: string, slot_key_hex: string): string;
@@ -154,6 +161,9 @@ export interface QCore {
   testnetChainId(): bigint;
   transaction_body(tx_id: string): string;
   valid_address(address: string): boolean;
+  sameAddress(a: string, b: string): boolean;
+  lookalikeOf(candidate: string, known: string[]): string | undefined;
+  vmCallFee(transfer_fee: WholeNumber, meter_limit: WholeNumber): bigint;
   vmDeployAddress(): string;
 }
 
@@ -255,3 +265,5 @@ export const core: QCore;
 export function generateSeed(): string;
 
 export function validUntil(nodeInfo: { head_height?: number | string | bigint }): bigint;
+
+export function vmCallFee(transferFee: WholeNumber, meterLimit: WholeNumber): bigint;

package/index.js

@@ -1,9 +1,11 @@
 // Copyright 2026 Quantova Inc
 // SPDX-License-Identifier: Apache-2.0 OR MIT
 
-const core = require('./pkg-node/qcore_js.js');
-const { makeClient, generateSeed, validUntil, Network } = require('./shared.js');
+const raw = require('./pkg-node/qcore_js.js');
+const { makeClient, wrapCore, generateSeed, validUntil, Network } = require('./shared.js');
 
+const core = wrapCore(raw);
 const Client = makeClient(core);
+const vmCallFee = core.vmCallFee;
 
-module.exports = { Client, core, generateSeed, validUntil, Network };
+module.exports = { Client, core, generateSeed, validUntil, vmCallFee, Network };

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@quantovainc/qcore",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Quantova's post quantum client core for JavaScript. Signs with ML-DSA-65 and builds Q1 addresses.",
   "scripts": {
     "build": "bash scripts/build.sh",
-    "test": "node test-entry-parity.mjs && node test-browser.mjs && node test-types.js && node test-conformance.js && node test-order-nonce.js && node test-chain-binding.js && node test-sign-validate.js && node test-transport.js && node test-fee-cap.js && node test-network.js && node test-typed-order.js && node test-asset-guards.js && node test-account-index.js"
+    "test": "node test-entry-parity.mjs && node --experimental-wasm-modules test-browser.mjs && node test-types.js && node test-conformance.js && node test-order-nonce.js && node test-chain-binding.js && node test-sign-validate.js && node test-transport.js && node test-fee-cap.js && node test-network.js && node test-typed-order.js && node test-asset-guards.js && node test-account-index.js"
   },
   "keywords": [
     "post-quantum",

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.2.0",
+  "version": "0.2.2",
   "license": "Apache-2.0 OR MIT",
   "repository": {
     "type": "git",

package/pkg/qcore_js.d.ts

@@ -17,12 +17,16 @@ export function buildTypedOrderCall(chain_id: bigint, contract: string, selector
 
 export function chainIdFromName(name: string): bigint;
 
+export function checkValidUntil(valid_until: bigint, head: bigint): void;
+
 export function contractAddress(deployer: string, nonce: bigint): string | undefined;
 
 export function eventsBody(height: bigint): string;
 
 export function localChainId(): bigint;
 
+export function lookalikeOf(candidate: string, known: string[]): string | undefined;
+
 export function mainnetChainId(): bigint;
 
 export function mapAddrWordKey(map_domain_tag: bigint, key32_hex: string, word: bigint): string;
@@ -41,17 +45,19 @@ export function packSymbol(symbol: string): bigint;
 
 export function parseEvents(response: string): string;
 
+export function sameAddress(a: string, b: string): boolean;
+
 export function scalarSlotKey(slot: bigint): string;
 
 export function seedFromMnemonic(phrase: string): any;
 
-export function signAssetCall(seed_hex: string, index: bigint, target: string, args_hex: string, asset_issuer: string, amount: string, nonce: bigint, meter_limit: bigint, fee: string, chain_id: bigint, valid_until: bigint): string;
+export function signAssetCall(seed_hex: string, index: bigint, target: string, args_hex: string, asset_issuer: string, amount: string, nonce: bigint, meter_limit: bigint, fee: string, chain_id: bigint, valid_until: bigint, transfer_fee?: string | null): string;
 
-export function signPayableCall(seed_hex: string, index: bigint, target: string, args_hex: string, nonce: bigint, meter_limit: bigint, fee: string, value: string, chain_id: bigint, valid_until: bigint): string;
+export function signPayableCall(seed_hex: string, index: bigint, target: string, args_hex: string, nonce: bigint, meter_limit: bigint, fee: string, value: string, chain_id: bigint, valid_until: bigint, transfer_fee?: string | null): string;
 
 export function signRegister(seed_hex: string, index: bigint, nonce: bigint, fee: string, chain_id: bigint, valid_until: bigint): string;
 
-export function sign_call(seed_hex: string, index: bigint, target: string, args_hex: string, nonce: bigint, meter_limit: bigint, fee: string, chain_id: bigint, valid_until: bigint): string;
+export function sign_call(seed_hex: string, index: bigint, target: string, args_hex: string, nonce: bigint, meter_limit: bigint, fee: string, chain_id: bigint, valid_until: bigint, transfer_fee?: string | null): string;
 
 export function sign_transfer(seed_hex: string, index: bigint, to: string, amount: string, nonce: bigint, fee: string, chain_id: bigint, valid_until: bigint): string;
 
@@ -73,4 +79,6 @@ export function unpackSymbol(word: bigint): string;
 
 export function valid_address(address: string): boolean;
 
+export function vmCallFee(transfer_fee: string, meter_limit: bigint): string;
+
 export function vmDeployAddress(): string;

package/pkg/qcore_js.js

@@ -5,5 +5,5 @@ import { __wbg_set_wasm } from "./qcore_js_bg.js";
 __wbg_set_wasm(wasm);
 wasm.__wbindgen_start();
 export {
-    account_body, address, assetBalanceBody, assetSupplyBody, block_by_height_body, buildSignedOrderCall, buildTypedOrderCall, chainIdFromName, contractAddress, eventsBody, localChainId, mainnetChainId, mapAddrWordKey, mapSlotKey, mnemonicFromSeed, nameKey, nonceSlotKey, orderSigner, packSymbol, parseEvents, scalarSlotKey, seedFromMnemonic, signAssetCall, signPayableCall, signRegister, sign_call, sign_transfer, storageBody, storageValue, submit_body, testnetChainId, tokenDecimalsSlot, tokenSymbolSlot, transaction_body, unpackSymbol, valid_address, vmDeployAddress
+    account_body, address, assetBalanceBody, assetSupplyBody, block_by_height_body, buildSignedOrderCall, buildTypedOrderCall, chainIdFromName, checkValidUntil, contractAddress, eventsBody, localChainId, lookalikeOf, mainnetChainId, mapAddrWordKey, mapSlotKey, mnemonicFromSeed, nameKey, nonceSlotKey, orderSigner, packSymbol, parseEvents, sameAddress, scalarSlotKey, seedFromMnemonic, signAssetCall, signPayableCall, signRegister, sign_call, sign_transfer, storageBody, storageValue, submit_body, testnetChainId, tokenDecimalsSlot, tokenSymbolSlot, transaction_body, unpackSymbol, valid_address, vmCallFee, vmDeployAddress
 } from "./qcore_js_bg.js";