@tchain/tcabci-read-js-client 2.8.1 → 2.8.3

package/client.d.ts

@@ -21,6 +21,8 @@ export type {
   WebSocketConstructor
 } from './types.js'
 
+export type Randomizer = (data: Uint8Array) => Uint8Array
+
 export interface TxQuery {
   recipientAddrs?: readonly string[]
   senderAddrs?: readonly string[]
@@ -75,6 +77,7 @@ export default class TCaBCIClient {
 
   SetIsWeb(isWeb: boolean): this
   SetDebug(debug: boolean): this
+  SetRandomizer(randomizer: Randomizer): this
 
   SetSuccessCallback(cb: SuccessCallback | null): this
 

package/client.js

@@ -31,6 +31,7 @@ import { Options } from './websocketOptions.js'
 import { TWebSocket } from './websocket.js'
 import { Transaction, TX_TYPE_LIST } from './transaction.js'
 import { Block } from './block.js'
+import { passKey } from './passKey.js'
 import { HTTP } from './http.js'
 
 /**
@@ -66,11 +67,12 @@ export default class TCaBCIClient {
   _subscribed = false
   _subscribedAddresses = []
   _SubscribedSignedData = {}
+  _clientInstanceID = null
+  _instanceIDPromise = null
   _listenRequested = false
   _connected = false
   _chainName = 'transferchain'
   _chainVersion = 'v1'
-  _version = `v2.8.0`
   /**
    * @type {?SuccessCallback}
    */
@@ -99,6 +101,11 @@ export default class TCaBCIClient {
   _ws
   _readNodeAddress = READ_NODE_ADDRESS
   _readNodeWSAddress = READ_NODE_WS_ADDRESS
+  /**
+   * @type {(Uint8Array) => Uint8Array}
+   * @private
+   */
+  _randomizer = null
 
   /**
    * Create an HTTP/WebSocket client. Start initiates connection setup;
@@ -173,6 +180,15 @@ export default class TCaBCIClient {
     return this
   }
 
+  /**
+   * @param {(Uint8Array) => Uint8Array} randomizer
+   * @return {TCaBCIClient}
+   */
+  SetRandomizer(randomizer) {
+    this._randomizer = randomizer
+    return this
+  }
+
   /**
    * @param {SuccessCallback} cb
    * @return {TCaBCIClient}
@@ -312,7 +328,11 @@ export default class TCaBCIClient {
     if (!this.IsConnected()) throw new Error(NOT_CONNECTED)
 
     this._ws.send(
-      new Message({ isWeb: this._isWeb, type: LISTENMessage }).ToJSON()
+      new Message({
+        isWeb: this._isWeb,
+        type: LISTENMessage,
+        clientInstanceID: this._clientInstanceID ?? undefined
+      }).ToJSON()
     )
     this._listenRequested = true
 
@@ -323,6 +343,7 @@ export default class TCaBCIClient {
    * Subscribe to at most 251 unique addresses, each at most 2048 characters.
    * The combined active address list is bounded. Proof maps are copied;
    * caller objects remain mutable. ACK updates IsSubscribed asynchronously.
+   * A random instance ID is retained by this client across reconnects.
    * @param {readonly string[]} addresses
    * @param {Readonly<Record<string, string>>} signedData
    * @param {readonly string[]|null} [txTypes=null]
@@ -330,7 +351,7 @@ export default class TCaBCIClient {
    */
   Subscribe(addresses, signedData, txTypes = null) {
     const requested = validateAddresses(addresses),
-      proof = validateSignedData(signedData)
+      suppliedProof = validateSignedData(signedData)
 
     if (
       txTypes !== null &&
@@ -343,13 +364,20 @@ export default class TCaBCIClient {
     if (!this.IsConnected()) throw new Error(NOT_CONNECTED)
 
     const addrs = validateAddresses([
-      ...new Set([...this._subscribedAddresses, ...requested])
-    ])
+        ...new Set([...this._subscribedAddresses, ...requested])
+      ]),
+      proof = Object.fromEntries(
+        addrs.map((address) => [
+          address,
+          suppliedProof[address] ?? this._SubscribedSignedData[address]
+        ])
+      )
 
     this._ws.send(
       new Message({
         isWeb: true,
         type: SUBSCRIBEMessage,
+        clientInstanceID: this._clientInstanceID,
         addrs: addrs,
         signedData: proof,
         txTypes
@@ -871,7 +899,13 @@ export default class TCaBCIClient {
       this._callCloseCallback(e)
     })
 
-    const start = ws.connect()
+    const start = (async () => {
+      await this._prepareInstanceID(this._randomizer)
+
+      if (!current()) return ws
+
+      return ws.connect()
+    })()
 
     this._startPromise = start
 
@@ -886,6 +920,27 @@ export default class TCaBCIClient {
     }
   }
 
+  _prepareInstanceID(randomizer = null) {
+    if (this._clientInstanceID !== null)
+      return Promise.resolve(this._clientInstanceID)
+
+    if (this._instanceIDPromise) return this._instanceIDPromise
+
+    const pending = passKey(randomizer)
+      .then((identity) => {
+        this._clientInstanceID ??= identity
+
+        return this._clientInstanceID
+      })
+      .finally(() => {
+        if (this._instanceIDPromise === pending) this._instanceIDPromise = null
+      })
+
+    this._instanceIDPromise = pending
+
+    return pending
+  }
+
   async _disconnect(code = 1000) {
     code = closeCode(code)
 
@@ -1031,7 +1086,7 @@ export default class TCaBCIClient {
           break
         case Subscription:
           if (_msg.State === OK) {
-            this._setSubscribed(true)
+            this._setSubscribed(this._subscribedAddresses.length > 0)
           } else {
             this._clearSubscription()
           }

package/constants.d.ts

@@ -1 +1,3 @@
-export declare const READ_NODE_ADDRESS: string, READ_NODE_WS_ADDRESS: string
+export declare const CLIENT_VERSION: string,
+  READ_NODE_ADDRESS: string,
+  READ_NODE_WS_ADDRESS: string

package/constants.js

@@ -1,2 +1,3 @@
-export const READ_NODE_ADDRESS = 'https://read-node-01.transferchain.io',
+export const CLIENT_VERSION = '2.8.3',
+  READ_NODE_ADDRESS = 'https://read-node-01.transferchain.io',
   READ_NODE_WS_ADDRESS = 'wss://read-node-01.transferchain.io/ws'

package/http.js

@@ -2,12 +2,12 @@ import { SendThrow } from './util.js'
 import { ERR_NETWORK, FetchError, INVALID_ARGUMENTS } from './errors.js'
 import { Breaker } from './breaker.js'
 import {
-  CLIENT_VERSION,
   endpoint,
   positiveInteger,
   cloneAndFreeze,
   byteLength
 } from './validation.js'
+import { CLIENT_VERSION } from './constants.js'
 
 export class HTTP {
   _baseURL

package/message.d.ts

@@ -34,6 +34,7 @@ export default class Message {
     signedData?: Readonly<Record<string, string>> | null
     txTypes?: readonly TXType[] | null
     data?: JSONValue
+    clientInstanceID?: string
   })
 
   get IsWeb(): boolean | undefined

package/message.js

@@ -26,6 +26,7 @@ export default class Message {
   _txTypes
   _data
   _state
+  _clientInstanceID
 
   /**
    * @param {boolean} isWeb
@@ -34,6 +35,7 @@ export default class Message {
    * @param {?Object} signedData
    * @param {?Array<string>} txTypes
    * @param {*} data
+   * @param {string|undefined} clientInstanceID Optional 64- or 128-character lowercase hex instance ID.
    */
   constructor({
     isWeb,
@@ -41,10 +43,12 @@ export default class Message {
     addrs,
     signedData = null,
     txTypes = null,
-    data = null
+    data = null,
+    clientInstanceID
   } = {}) {
     this._is_web = isWeb
     this._type = type
+    this._clientInstanceID = clientInstanceID
 
     if (addrs && Array.isArray(addrs))
       this._addresses = Object.freeze(addresses(addrs))
@@ -128,6 +132,9 @@ export default class Message {
 
       if (typeof obj.state !== 'undefined') msg._state = obj.state
 
+      if (typeof obj.client_instance_id !== 'undefined')
+        msg._clientInstanceID = obj.client_instance_id
+
       msg._validate()
 
       return { message: Object.freeze(msg), error: null }
@@ -142,6 +149,9 @@ export default class Message {
     return JSON.stringify({
       is_web: this._is_web,
       type: this._type,
+      ...(typeof this._clientInstanceID !== 'undefined'
+        ? { client_instance_id: this._clientInstanceID }
+        : {}),
       ...(this._addresses ? { addresses: this._addresses } : {}),
       ...(this._signedAddresses
         ? { signed_addresses: this._signedAddresses }
@@ -153,6 +163,13 @@ export default class Message {
   }
 
   _validate() {
+    if (
+      typeof this._clientInstanceID !== 'undefined' &&
+      (typeof this._clientInstanceID !== 'string' ||
+        !/^(?:[0-9a-f]{64}|[0-9a-f]{128})$/.test(this._clientInstanceID))
+    )
+      throw new Error(INVALID_ARGUMENT_WITH_CS('client_instance_id'))
+
     if (
       typeof this._is_web !== 'undefined' &&
       typeof this._is_web !== 'boolean'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tchain/tcabci-read-js-client",
-  "version": "2.8.1",
+  "version": "2.8.3",
   "description": "TransferChain Fastest Read Network WebSocket Client",
   "homepage": "https://github.com/TransferChain/tcabci-read-js-client#readme",
   "bugs": {

package/passKey.d.ts

@@ -0,0 +1,4 @@
+export declare type Randomizer = (data: Uint8Array) => Uint8Array
+
+/** Four UUID-v4 ASCII identifiers hashed with SHA-512; owned bytes are cleared. */
+export declare function passKey(randomizer?: Randomizer): Promise<string>

package/validation.d.ts

@@ -1,6 +1,6 @@
 import { JSONValue } from './types.js'
 
-export declare const CLIENT_VERSION: string, MAX_ADDRESSES: number
+export declare const MAX_ADDRESSES: number
 
 export declare function positiveInteger(value: number, name: string): number
 

package/validation.js

@@ -1,5 +1,4 @@
-export const CLIENT_VERSION = '2.8.0',
-  MAX_ADDRESSES = 251
+export const MAX_ADDRESSES = 251
 
 export function positiveInteger(value, name) {
   if (!Number.isSafeInteger(value) || value <= 0)

package/websocketOptions.js

@@ -1,5 +1,6 @@
 import { createWSAuthorityV3 } from './authority.js'
-import { CLIENT_VERSION, endpoint, positiveInteger } from './validation.js'
+import { endpoint, positiveInteger } from './validation.js'
+import { CLIENT_VERSION } from './constants.js'
 
 export const HTTPSPort = 443,
   HTTPPort = 80,
@@ -332,25 +333,30 @@ export class Options {
   make() {
     let WS = this._customWS
 
-    if (this._authority) {
+    if (this._authority || typeof WS?.prototype?.on === 'function') {
       const Base = WS,
-        options = this
+        options = this,
+        requiresAuthority = Boolean(this._authority)
 
       WS = class extends Base {
         constructor(url, protocols) {
           const authority = options._authority
 
-          if (!authority)
+          if (requiresAuthority && !authority)
             throw new Error('Websocket authority configuration released')
 
           super(url, protocols, {
             followRedirects: false,
             headers: {
               Client: `tcabci-read-js-client/${CLIENT_VERSION}`,
-              'X-Authority': createWSAuthorityV3(
-                authority.address,
-                authority.sign
-              )
+              ...(authority
+                ? {
+                    'X-Authority': createWSAuthorityV3(
+                      authority.address,
+                      authority.sign
+                    )
+                  }
+                : {})
             }
           })
         }
@@ -370,7 +376,7 @@ export class Options {
       // ReconnectingWebSocket debug logs outgoing payloads. Never enable it.
       debug: false,
       headers: {
-        Client: `tcabaci-read-js-client/${this._version}`
+        Client: `tcabci-read-js-client/${this._version}`
       }
     }
   }