@quantovainc/qcore 0.5.5 → 0.5.7

package/README.md

@@ -134,6 +134,13 @@ Pass `addressBook`, a list of Q1 addresses you trust, in the Client options, and
 a target that shares two or more leading and trailing characters with a known address, eight in all, but is a
 different address. The sending accounts and every target signed for in the session are known as well.
 
+Pass `fetch`, a function with the fetch signature, in the Client options to route every gateway request
+through your own transport, for example one that enforces an address allow list. Without it the Client
+uses the platform fetch, which on Node follows HTTPS_PROXY only when NODE_USE_ENV_PROXY is set. The
+Client refuses to start when NODE_TLS_REJECT_UNAUTHORIZED is 0. Signing calls for one account run one at a
+time across every Client in the process, and each Client keeps its own record of signed nonces, so keep
+one Client per account to have every nonce tracked in one place.
+
 The last argument to a Client signing call, transfer, register, call, or callSignedOrder, is a fee
 ceiling, the most you are ever willing to pay in fees for one transaction. You choose it yourself, as a
 fixed number your app decides on its own, before you sign. The Client reads the gateway's reported fee,
@@ -148,7 +155,10 @@ 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, 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 gateway you do not control reports the fee. The raw signing functions also take the validity deadline
+ready made and do not compare it with the chain head, so call core.checkValidUntil with a head you trust
+first. A SigningSession reserves each nonce it hands out until it is signed, and a flow that stops early
+frees its nonce with release.
 
 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

package/index.d.ts

@@ -212,6 +212,8 @@ export interface SigningSession {
   rememberAddress(address: string): void;
   checkTarget(address: string): void;
   slot(key: string, reported: bigint, expected: bigint | undefined, order: boolean): bigint;
+  release(key: string, slot: bigint): void;
+  releasePending(key: string): void;
   signed(key: string, slot: bigint): void;
   outcome(key: string, slot: bigint, accepted: boolean): void;
   nextNonce(key: string): bigint | undefined;
@@ -237,6 +239,7 @@ export interface ClientOptions {
   network?: Network;
   expectedChainId?: string;
   addressBook?: ReadonlyArray<string>;
+  fetch?: (url: string, init: { method: string; headers: Record<string, string>; body: string; signal: AbortSignal; redirect: 'error' }) => Promise<Response>;
 }
 
 export class Client {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quantovainc/qcore",
-  "version": "0.5.5",
+  "version": "0.5.7",
   "description": "Quantova's post quantum client core for JavaScript. Signs with ML-DSA-65 and builds Q1 addresses.",
   "scripts": {
     "build": "bash scripts/build.sh",

package/pkg/README.md

@@ -134,6 +134,13 @@ Pass `addressBook`, a list of Q1 addresses you trust, in the Client options, and
 a target that shares two or more leading and trailing characters with a known address, eight in all, but is a
 different address. The sending accounts and every target signed for in the session are known as well.
 
+Pass `fetch`, a function with the fetch signature, in the Client options to route every gateway request
+through your own transport, for example one that enforces an address allow list. Without it the Client
+uses the platform fetch, which on Node follows HTTPS_PROXY only when NODE_USE_ENV_PROXY is set. The
+Client refuses to start when NODE_TLS_REJECT_UNAUTHORIZED is 0. Signing calls for one account run one at a
+time across every Client in the process, and each Client keeps its own record of signed nonces, so keep
+one Client per account to have every nonce tracked in one place.
+
 The last argument to a Client signing call, transfer, register, call, or callSignedOrder, is a fee
 ceiling, the most you are ever willing to pay in fees for one transaction. You choose it yourself, as a
 fixed number your app decides on its own, before you sign. The Client reads the gateway's reported fee,
@@ -148,7 +155,10 @@ 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, 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 gateway you do not control reports the fee. The raw signing functions also take the validity deadline
+ready made and do not compare it with the chain head, so call core.checkValidUntil with a head you trust
+first. A SigningSession reserves each nonce it hands out until it is signed, and a flow that stops early
+frees its nonce with release.
 
 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

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

package/pkg/qcore_js.d.ts

@@ -9,6 +9,8 @@ export class SigningSession {
     constructor(book: string[]);
     nextNonce(key: string): bigint | undefined;
     outcome(key: string, slot: bigint, accepted: boolean): void;
+    release(key: string, slot: bigint): void;
+    releasePending(key: string): void;
     rememberAddress(address: string): void;
     signed(key: string, slot: bigint): void;
     slot(key: string, reported: bigint, expected: bigint | null | undefined, order: boolean): bigint;

package/pkg/qcore_js_bg.js

@@ -65,6 +65,23 @@ export class SigningSession {
         const len0 = WASM_VECTOR_LEN;
         wasm.signingsession_outcome(this.__wbg_ptr, ptr0, len0, slot, accepted);
     }
+    /**
+     * @param {string} key
+     * @param {bigint} slot
+     */
+    release(key, slot) {
+        const ptr0 = passStringToWasm0(key, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        wasm.signingsession_release(this.__wbg_ptr, ptr0, len0, slot);
+    }
+    /**
+     * @param {string} key
+     */
+    releasePending(key) {
+        const ptr0 = passStringToWasm0(key, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        wasm.signingsession_releasePending(this.__wbg_ptr, ptr0, len0);
+    }
     /**
      * @param {string} address
      */

package/pkg/qcore_js_bg.wasm.d.ts

@@ -46,6 +46,8 @@ export const signingsession_isHeld: (a: number, b: number, c: number, d: bigint)
 export const signingsession_new: (a: number, b: number) => [number, number, number];
 export const signingsession_nextNonce: (a: number, b: number, c: number) => [number, bigint];
 export const signingsession_outcome: (a: number, b: number, c: number, d: bigint, e: number) => void;
+export const signingsession_release: (a: number, b: number, c: number, d: bigint) => void;
+export const signingsession_releasePending: (a: number, b: number, c: number) => void;
 export const signingsession_rememberAddress: (a: number, b: number, c: number) => void;
 export const signingsession_signed: (a: number, b: number, c: number, d: bigint) => void;
 export const signingsession_slot: (a: number, b: number, c: number, d: bigint, e: number, f: bigint, g: number) => [bigint, number, number];

package/pkg-node/README.md

@@ -134,6 +134,13 @@ Pass `addressBook`, a list of Q1 addresses you trust, in the Client options, and
 a target that shares two or more leading and trailing characters with a known address, eight in all, but is a
 different address. The sending accounts and every target signed for in the session are known as well.
 
+Pass `fetch`, a function with the fetch signature, in the Client options to route every gateway request
+through your own transport, for example one that enforces an address allow list. Without it the Client
+uses the platform fetch, which on Node follows HTTPS_PROXY only when NODE_USE_ENV_PROXY is set. The
+Client refuses to start when NODE_TLS_REJECT_UNAUTHORIZED is 0. Signing calls for one account run one at a
+time across every Client in the process, and each Client keeps its own record of signed nonces, so keep
+one Client per account to have every nonce tracked in one place.
+
 The last argument to a Client signing call, transfer, register, call, or callSignedOrder, is a fee
 ceiling, the most you are ever willing to pay in fees for one transaction. You choose it yourself, as a
 fixed number your app decides on its own, before you sign. The Client reads the gateway's reported fee,
@@ -148,7 +155,10 @@ 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, 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 gateway you do not control reports the fee. The raw signing functions also take the validity deadline
+ready made and do not compare it with the chain head, so call core.checkValidUntil with a head you trust
+first. A SigningSession reserves each nonce it hands out until it is signed, and a flow that stops early
+frees its nonce with release.
 
 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

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

package/pkg-node/qcore_js.d.ts

@@ -9,6 +9,8 @@ export class SigningSession {
     constructor(book: string[]);
     nextNonce(key: string): bigint | undefined;
     outcome(key: string, slot: bigint, accepted: boolean): void;
+    release(key: string, slot: bigint): void;
+    releasePending(key: string): void;
     rememberAddress(address: string): void;
     signed(key: string, slot: bigint): void;
     slot(key: string, reported: bigint, expected: bigint | null | undefined, order: boolean): bigint;

package/pkg-node/qcore_js.js

@@ -67,6 +67,23 @@ class SigningSession {
         const len0 = WASM_VECTOR_LEN;
         wasm.signingsession_outcome(this.__wbg_ptr, ptr0, len0, slot, accepted);
     }
+    /**
+     * @param {string} key
+     * @param {bigint} slot
+     */
+    release(key, slot) {
+        const ptr0 = passStringToWasm0(key, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        wasm.signingsession_release(this.__wbg_ptr, ptr0, len0, slot);
+    }
+    /**
+     * @param {string} key
+     */
+    releasePending(key) {
+        const ptr0 = passStringToWasm0(key, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        wasm.signingsession_releasePending(this.__wbg_ptr, ptr0, len0);
+    }
     /**
      * @param {string} address
      */

package/shared.js

@@ -59,6 +59,20 @@ function wholeNumber(value, label, max) {
   return n;
 }
 
+const ACCOUNT_LOCKS = new Map();
+
+function requireVerifiedTls() {
+  const env = typeof process !== 'undefined' && process && process.env ? process.env : null;
+  if (env && env.NODE_TLS_REJECT_UNAUTHORIZED === '0') {
+    throw new Error('this process has TLS certificate checks turned off with NODE_TLS_REJECT_UNAUTHORIZED=0, refusing to talk to a gateway');
+  }
+}
+
+function shown(value) {
+  const text = String(value).replace(/[\u0000-\u001f\u007f-\u009f\u200b-\u200f\u2028-\u202e\u2066-\u2069\ufeff]/g, '');
+  return text.length > 96 ? text.slice(0, 96) + '...' : text;
+}
+
 function coreArg(kind, label, value) {
   if (kind === 'text') {
     if (typeof value !== 'string') throw new Error(`the ${label} must be a string`);
@@ -343,7 +357,10 @@ function makeClient(core) {
       this._session = new core.SigningSession(book);
       this._pinnedChainName = null;
       this._headFloor = null;
-      this._locks = new Map();
+      if (opts.fetch != null && typeof opts.fetch !== 'function') throw new Error('the fetch option must be a function with the fetch signature');
+      this._fetch = opts.fetch || ((url, init) => fetch(url, init));
+      requireVerifiedTls();
+      this._locks = ACCOUNT_LOCKS;
       for (const name of ['transfer', 'register', 'call', 'assetCall', 'payableCall']) {
         const inner = this[name].bind(this);
         this[name] = (seed, index, ...rest) => {
@@ -392,18 +409,18 @@ function makeClient(core) {
       const mainnet = isMainnetChain(name);
       if (configured) {
         if (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`);
+          throw new Error(`the gateway reports chain ${shown(name)} but this client is configured for ${configured}; refusing to sign a transaction that would be valid on a network you did not choose`);
         }
       } else if (isPublicChain(name) && !(mainnet && this.acknowledgeMainnet)) {
-        throw new Error(`the gateway reports the public chain ${name} but this client was opened for an unnamed network; configure the testnet or mainnet network before signing for it`);
+        throw new Error(`the gateway reports the public chain ${shown(name)} but this client was opened for an unnamed network; configure the testnet or mainnet network before signing for it`);
       }
       if (mainnet && !this.acknowledgeMainnet) {
-        throw new Error(`the gateway reports the mainnet chain ${name}; refusing to sign a mainnet transaction without acknowledgeMainnet`);
+        throw new Error(`the gateway reports the mainnet chain ${shown(name)}; refusing to sign a mainnet transaction without acknowledgeMainnet`);
       }
       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`);
+        throw new Error(`the gateway reported chain ${shown(this._pinnedChainName)} earlier and now reports ${shown(name)}; refusing to sign, the endpoint is not naming one network`);
       }
       return BigInt(core.chainIdFromName(name));
     }
@@ -412,7 +429,7 @@ function makeClient(core) {
       const controller = new AbortController();
       const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
       try {
-        const res = await fetch(this.base + '/v1/' + method, {
+        const res = await this._fetch(this.base + '/v1/' + method, {
           method: 'POST',
           headers: { 'Content-Type': 'application/json' },
           body: body || '{}',
@@ -425,7 +442,7 @@ function makeClient(core) {
         try { data = JSON.parse(text); } catch { throw new Error('the node returned a non JSON response'); }
         if (res.status !== 200) {
           const detail = data && typeof data === 'object' ? (data.message || data.error) : null;
-          throw new Error(detail || ('status ' + res.status));
+          throw new Error(detail ? shown(detail) : ('status ' + res.status));
         }
         return data;
       } finally {
@@ -441,7 +458,7 @@ function makeClient(core) {
         throw new Error(`the gateway answered about ${address} without naming the account, refusing to trust it`);
       }
       if (acct.address !== address) {
-        throw new Error(`the gateway answered for ${acct.address} when asked about ${address}, refusing to trust it`);
+        throw new Error(`the gateway answered for ${shown(acct.address)} when asked about ${address}, refusing to trust it`);
       }
       return acct;
     }
@@ -462,6 +479,7 @@ function makeClient(core) {
     async _accountSlot(from, expectedNonce) {
       const acct = await this.account(from);
       const reported = gatewayInteger(acct.nonce, 'nonce');
+      this._session.releasePending(from);
       return BigInt(this._session.slot(from, reported, this._expected(expectedNonce, 'expected nonce'), false));
     }
 
@@ -469,7 +487,7 @@ function makeClient(core) {
       for (const [key, slot] of slots) this._session.signed(key, slot);
       const outcome = await this.submit(txHex);
       const verdict = outcome && outcome.verdict;
-      if (verdict !== 'accepted' && verdict !== 'rejected') throw new Error(`unknown verdict ${verdict}`);
+      if (verdict !== 'accepted' && verdict !== 'rejected') throw new Error(`unknown verdict ${shown(verdict)}`);
       for (const [key, slot] of slots) this._session.outcome(key, slot, verdict === 'accepted');
       return outcome;
     }
@@ -649,6 +667,7 @@ function makeClient(core) {
       const signer = core.orderSigner(ownerSeed, accountIndex(ownerIndex));
       const orderKey = contract + '/' + signer;
       const reportedOrder = await this.contractNonce(contract, signer);
+      this._session.releasePending(orderKey);
       const nonce = BigInt(this._session.slot(orderKey, reportedOrder, this._expected(expectedOrderNonce, 'expected order nonce'), true));
       if (typeof orderSpec.layoutHash !== 'string') throw new Error('the order spec needs the layout hash the compiler emits for this entry');
       const orderExpiry = wholeNumber(orderSpec.expiry, 'order expiry', U64_MAX);

package/shared.mjs

@@ -59,6 +59,20 @@ function wholeNumber(value, label, max) {
   return n;
 }
 
+const ACCOUNT_LOCKS = new Map();
+
+function requireVerifiedTls() {
+  const env = typeof process !== 'undefined' && process && process.env ? process.env : null;
+  if (env && env.NODE_TLS_REJECT_UNAUTHORIZED === '0') {
+    throw new Error('this process has TLS certificate checks turned off with NODE_TLS_REJECT_UNAUTHORIZED=0, refusing to talk to a gateway');
+  }
+}
+
+function shown(value) {
+  const text = String(value).replace(/[\u0000-\u001f\u007f-\u009f\u200b-\u200f\u2028-\u202e\u2066-\u2069\ufeff]/g, '');
+  return text.length > 96 ? text.slice(0, 96) + '...' : text;
+}
+
 function coreArg(kind, label, value) {
   if (kind === 'text') {
     if (typeof value !== 'string') throw new Error(`the ${label} must be a string`);
@@ -343,7 +357,10 @@ function makeClient(core) {
       this._session = new core.SigningSession(book);
       this._pinnedChainName = null;
       this._headFloor = null;
-      this._locks = new Map();
+      if (opts.fetch != null && typeof opts.fetch !== 'function') throw new Error('the fetch option must be a function with the fetch signature');
+      this._fetch = opts.fetch || ((url, init) => fetch(url, init));
+      requireVerifiedTls();
+      this._locks = ACCOUNT_LOCKS;
       for (const name of ['transfer', 'register', 'call', 'assetCall', 'payableCall']) {
         const inner = this[name].bind(this);
         this[name] = (seed, index, ...rest) => {
@@ -392,18 +409,18 @@ function makeClient(core) {
       const mainnet = isMainnetChain(name);
       if (configured) {
         if (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`);
+          throw new Error(`the gateway reports chain ${shown(name)} but this client is configured for ${configured}; refusing to sign a transaction that would be valid on a network you did not choose`);
         }
       } else if (isPublicChain(name) && !(mainnet && this.acknowledgeMainnet)) {
-        throw new Error(`the gateway reports the public chain ${name} but this client was opened for an unnamed network; configure the testnet or mainnet network before signing for it`);
+        throw new Error(`the gateway reports the public chain ${shown(name)} but this client was opened for an unnamed network; configure the testnet or mainnet network before signing for it`);
       }
       if (mainnet && !this.acknowledgeMainnet) {
-        throw new Error(`the gateway reports the mainnet chain ${name}; refusing to sign a mainnet transaction without acknowledgeMainnet`);
+        throw new Error(`the gateway reports the mainnet chain ${shown(name)}; refusing to sign a mainnet transaction without acknowledgeMainnet`);
       }
       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`);
+        throw new Error(`the gateway reported chain ${shown(this._pinnedChainName)} earlier and now reports ${shown(name)}; refusing to sign, the endpoint is not naming one network`);
       }
       return BigInt(core.chainIdFromName(name));
     }
@@ -412,7 +429,7 @@ function makeClient(core) {
       const controller = new AbortController();
       const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
       try {
-        const res = await fetch(this.base + '/v1/' + method, {
+        const res = await this._fetch(this.base + '/v1/' + method, {
           method: 'POST',
           headers: { 'Content-Type': 'application/json' },
           body: body || '{}',
@@ -425,7 +442,7 @@ function makeClient(core) {
         try { data = JSON.parse(text); } catch { throw new Error('the node returned a non JSON response'); }
         if (res.status !== 200) {
           const detail = data && typeof data === 'object' ? (data.message || data.error) : null;
-          throw new Error(detail || ('status ' + res.status));
+          throw new Error(detail ? shown(detail) : ('status ' + res.status));
         }
         return data;
       } finally {
@@ -441,7 +458,7 @@ function makeClient(core) {
         throw new Error(`the gateway answered about ${address} without naming the account, refusing to trust it`);
       }
       if (acct.address !== address) {
-        throw new Error(`the gateway answered for ${acct.address} when asked about ${address}, refusing to trust it`);
+        throw new Error(`the gateway answered for ${shown(acct.address)} when asked about ${address}, refusing to trust it`);
       }
       return acct;
     }
@@ -462,6 +479,7 @@ function makeClient(core) {
     async _accountSlot(from, expectedNonce) {
       const acct = await this.account(from);
       const reported = gatewayInteger(acct.nonce, 'nonce');
+      this._session.releasePending(from);
       return BigInt(this._session.slot(from, reported, this._expected(expectedNonce, 'expected nonce'), false));
     }
 
@@ -469,7 +487,7 @@ function makeClient(core) {
       for (const [key, slot] of slots) this._session.signed(key, slot);
       const outcome = await this.submit(txHex);
       const verdict = outcome && outcome.verdict;
-      if (verdict !== 'accepted' && verdict !== 'rejected') throw new Error(`unknown verdict ${verdict}`);
+      if (verdict !== 'accepted' && verdict !== 'rejected') throw new Error(`unknown verdict ${shown(verdict)}`);
       for (const [key, slot] of slots) this._session.outcome(key, slot, verdict === 'accepted');
       return outcome;
     }
@@ -649,6 +667,7 @@ function makeClient(core) {
       const signer = core.orderSigner(ownerSeed, accountIndex(ownerIndex));
       const orderKey = contract + '/' + signer;
       const reportedOrder = await this.contractNonce(contract, signer);
+      this._session.releasePending(orderKey);
       const nonce = BigInt(this._session.slot(orderKey, reportedOrder, this._expected(expectedOrderNonce, 'expected order nonce'), true));
       if (typeof orderSpec.layoutHash !== 'string') throw new Error('the order spec needs the layout hash the compiler emits for this entry');
       const orderExpiry = wholeNumber(orderSpec.expiry, 'order expiry', U64_MAX);