@quantovainc/qcore 0.1.27 → 0.1.30

package/README.md

@@ -18,6 +18,8 @@ npm install @quantovainc/qcore
 ```js
 const { Client, core, generateSeed } = require('@quantovainc/qcore');
 
+const GATEWAY = 'https://rpc-testnet.quantova.org';
+
 async function main() {
   // Create an account. The seed is the only backup and it never leaves the device.
   const seed = generateSeed();
@@ -28,12 +30,39 @@ async function main() {
   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');
+  // 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);
 
   // 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';
 
+  // A new account holds nothing, so take testnet funds before anything else.
+  // The faucet sends 10, 50 or 100 TQTOV to one address at a time.
+  await fetch(GATEWAY + '/faucet/api/claim', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ address: from, amount: 10 }),
+  });
+
+  // The faucet pays you with a transaction, so wait for the balance to arrive before spending it.
+  for (let i = 0; i < 40; i += 1) {
+    const funded = await client.account(from).catch(() => null);
+    if (funded && BigInt(funded.balance || 0) > 0n) break;
+    await new Promise((wake) => setTimeout(wake, 1500));
+  }
+
+  // An account publishes its key once before it is allowed to send. This happens a single
+  // time for each account and it pays a fee like any other transaction.
+  await client.register(seed, 0, MAX_FEE_QUON);
+
+  // Registration is itself a transaction, so wait for the key to be on chain.
+  for (let i = 0; i < 30; i += 1) {
+    const ready = await client.account(from).catch(() => null);
+    if (ready && ready.has_key) break;
+    await new Promise((wake) => setTimeout(wake, 1500));
+  }
+
   // 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);

package/index.d.ts

@@ -162,6 +162,8 @@ export class Network {
 export interface ClientOptions {
   acknowledgeMainnet?: boolean;
   network?: Network;
+  /** Bind signatures to this chain name; a gateway reporting any other is refused. */
+  expectedChainId?: string;
 }
 
 export class Client {
@@ -228,6 +230,7 @@ export class Client {
     ownerIndex: number,
     meterLimit: number | bigint,
     maxFeeQuon: string | bigint,
+    expectedOrderNonce?: bigint | number | string
   ): Promise<SignedOrderResult>;
 }
 

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@quantovainc/qcore",
-  "version": "0.1.27",
+  "version": "0.1.30",
   "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-conformance.js && node test-sign-validate.js && node test-transport.js && node test-fee-cap.js && node test-network.js"
+    "test": "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"
   },
   "keywords": [
     "post-quantum",
@@ -83,5 +83,8 @@
   ],
   "engines": {
     "node": ">=18"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0"
   }
 }

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.27",
+  "version": "0.1.29",
   "license": "Apache-2.0 OR MIT",
   "repository": {
     "type": "git",
@@ -13,8 +13,8 @@
     "qcore_js.js",
     "qcore_js_bg.js",
     "qcore_js.d.ts",
-    "LICENSE-APACHE",
-    "LICENSE-MIT"
+    "LICENSE-MIT",
+    "LICENSE-APACHE"
   ],
   "main": "qcore_js.js",
   "types": "qcore_js.d.ts",

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.27",
+  "version": "0.1.29",
   "license": "Apache-2.0 OR MIT",
   "repository": {
     "type": "git",
@@ -11,8 +11,8 @@
     "qcore_js_bg.wasm",
     "qcore_js.js",
     "qcore_js.d.ts",
-    "LICENSE-APACHE",
-    "LICENSE-MIT"
+    "LICENSE-MIT",
+    "LICENSE-APACHE"
   ],
   "main": "qcore_js.js",
   "types": "qcore_js.d.ts"

package/shared.js

@@ -146,7 +146,7 @@ class Network {
   static testnet() {
     return new Network({
       name: 'testnet',
-      chainId: 'Q-test-net-1',
+      chainId: 'Q-test-net-3',
       rpcUrl: 'https://rpc-testnet.quantova.org',
       explorerUrl: 'https://qvmscan.io',
       isMainnet: false,
@@ -198,6 +198,17 @@ function makeClient(core) {
         this.network = opts.network instanceof Network ? opts.network : Network.forUrl(base);
       }
       this.base = requireSafeTransport(base).replace(/\/$/, '');
+      // The chain name the gateway reports is hashed into the signature preimage of
+      // every signing path, so whoever names it decides which network a signature is
+      // valid on. `Network.forUrl` leaves chainId null, which is the default for
+      // `new Client(url)`, and the configured check is skipped when it is null, so by
+      // default the endpoint chose. Bind it with expectedChainId, or rely on the pin,
+      // which at least refuses a gateway that changes its mind mid session.
+      this.expectedChainId =
+        typeof opts.expectedChainId === 'string' && opts.expectedChainId.length > 0
+          ? opts.expectedChainId
+          : null;
+      this._pinnedChainName = null;
     }
 
     _guardMainnet() {
@@ -212,13 +223,25 @@ function makeClient(core) {
       if (!name) throw new Error('the gateway did not report a chain id to bind the signature to');
       if (typeof name !== 'string') throw new Error('the gateway reported a chain id that is not a string, refusing to bind a signature to it');
       const id = BigInt(core.chainIdFromName(name));
-      const configured = this.network && this.network.chainId;
+      const configured =
+        this.expectedChainId || (this.network && this.network.chainId) || null;
       if (configured && name !== configured) {
         throw new Error(`the gateway reports chain ${name} but this client is configured for ${configured}; refusing to sign a transaction that would be valid on a network you did not choose`);
       }
       if (!this.acknowledgeMainnet && this._isMainnetId(id)) {
         throw new Error(`the gateway reports the mainnet chain ${name}; refusing to sign a mainnet transaction without acknowledgeMainnet`);
       }
+      // Pin on first ACCEPTED use, after every refusal above. With nothing configured
+      // the endpoint names the chain, and the least this can do is refuse one that
+      // answers differently later in the same session, which is how a signature ends
+      // up bound to a network the caller never chose while every earlier call looked
+      // entirely normal. Pinning a name we refused to sign for would be wrong: it was
+      // never a chain this client accepted.
+      if (this._pinnedChainName === null) {
+        this._pinnedChainName = name;
+      } else if (this._pinnedChainName !== name) {
+        throw new Error(`the gateway reported chain ${this._pinnedChainName} earlier and now reports ${name}; refusing to sign, the endpoint is not naming one network`);
+      }
       return id;
     }
 
@@ -378,7 +401,7 @@ function makeClient(core) {
       return BigInt(core.storageValue(JSON.stringify(resp), core.scalarSlotKey(BigInt(slot))));
     }
 
-    async callSignedOrder(callerSeedHex, callerIndex, contract, selectorHex, orderSpec, ownerSeedHex, ownerIndex, meterLimit, maxFeeQuon) {
+    async callSignedOrder(callerSeedHex, callerIndex, contract, selectorHex, orderSpec, ownerSeedHex, ownerIndex, meterLimit, maxFeeQuon, expectedOrderNonce) {
       if (!core.valid_address(contract)) throw new Error('the contract is not a q1 address');
       const ceiling = feeCeiling(maxFeeQuon);
       const info = await this.nodeInfo();
@@ -390,7 +413,18 @@ function makeClient(core) {
         throw new Error(`the gateway fee ${fee} is above the maximum you allowed ${maxFeeQuon}, refusing to sign`);
       }
       const signer = core.orderSigner(ownerSeedHex, accountIndex(ownerIndex));
+      // The owner authorisation carries no deadline, so this nonce is the only thing
+      // that stops it being replayed. Reading it from the gateway hands the party the
+      // signature protects against the one term that expires it: answer with a future
+      // nonce and the reply is a valid order banked until the contract counter reaches
+      // it. Pass expectedOrderNonce to bind what you meant to sign; without it you are
+      // trusting the endpoint with the owner key.
       const nonce = await this.contractNonce(contract, signer);
+      if (expectedOrderNonce != null && BigInt(expectedOrderNonce) !== nonce) {
+        throw new Error(
+          `the gateway reported order nonce ${nonce} but you expected ${expectedOrderNonce}, refusing to sign`
+        );
+      }
       const order = JSON.parse(core.buildTypedOrderCall(
         chainId,
         contract,
@@ -410,7 +444,7 @@ function makeClient(core) {
         core.sign_call(callerSeedHex, accountIndex(callerIndex), contract, order.call_args, accountNonce(acct.nonce), BigInt(meterLimit), String(fee), chainId)
       );
       const outcome = await this.submit(signed.tx_hex);
-      return { order, signed, outcome };
+      return { order, signed, outcome, orderNonce: nonce };
     }
   };
 }