@tchain/tcabci-read-js-client 2.7.12 → 2.8.0

package/client.js

@@ -1,3 +1,10 @@
+import {
+  addresses as validateAddresses,
+  signedData as validateSignedData,
+  endpoint,
+  closeCode,
+  rfc3339Timestamp
+} from './validation.js'
 import {
   ALREADY_CONNECTED,
   BLOCK_NOT_FOUND,
@@ -25,7 +32,7 @@ import { HTTP } from './http.js'
 
 /**
  * @callback SuccessCallback
- * @param {Transaction} event
+ * @param {Event} event
  * @return void
  */
 
@@ -50,14 +57,16 @@ import { HTTP } from './http.js'
  */
 
 export default class TCaBCIClient {
-  _httpClient = new HTTP()
+  _httpClient
+  _startPromise = null
+  _generation = 0
   _subscribed = false
   _subscribedAddresses = []
   _SubscribedSignedData = {}
   _connected = false
   _chainName = 'transferchain'
   _chainVersion = 'v1'
-  _version = `v2.7.12`
+  _version = `v2.8.0`
   /**
    * @type {?SuccessCallback}
    */
@@ -88,40 +97,66 @@ export default class TCaBCIClient {
   _readNodeWSAddress = READ_NODE_WS_ADDRESS
 
   /**
-   * @param {Array<String>} readNodeAddresses
-   * @param {WebSocket} wsLibrary
-   * @param {?string} chainName
-   * @param {?string} chainVersion
+   * Create an HTTP/WebSocket client. Start initiates connection setup;
+   * SetSuccessCallback reports when the socket is OPEN.
+   * @param {string[]} [readNodeAddresses=[]] HTTP and WS endpoints, or defaults.
+   * @param {import('./types.js').WebSocketConstructor} [wsLibrary=globalThis.WebSocket]
+   * @param {string|null} [chainName=null]
+   * @param {string|null} [chainVersion=null]
+   * @param {import('./types.js').ClientOptions} [options={}] Limits and TLS policy.
    */
   constructor(
     readNodeAddresses = [],
-    wsLibrary,
+    wsLibrary = globalThis.WebSocket,
     chainName = null,
-    chainVersion = null
+    chainVersion = null,
+    options = {}
   ) {
     if (!wsLibrary) throw new Error(INVALID_ARGUMENTS)
-    this._wsLibrary = wsLibrary
 
-    if (Array.isArray(readNodeAddresses) && readNodeAddresses.length === 2) {
-      if (!readNodeAddresses[0].startsWith('http'))
-        throw new Error(INVALID_ARGUMENTS)
-      if (!readNodeAddresses[1].startsWith('ws'))
-        throw new Error(INVALID_ARGUMENTS)
+    this._wsLibrary = wsLibrary
 
-      this._readNodeAddress = readNodeAddresses[0]
-      this._readNodeWSAddress = readNodeAddresses[1]
-      this._httpClient.setBaseURL(readNodeAddresses[0])
+    if (
+      !Array.isArray(readNodeAddresses) ||
+      ![0, 2].includes(readNodeAddresses.length)
+    )
+      throw new Error(INVALID_ARGUMENTS)
+
+    if (readNodeAddresses.length === 2) {
+      this._readNodeAddress = endpoint(
+        readNodeAddresses[0],
+        ['https:', 'http:'],
+        options.allowInsecure
+      ).href
+      this._readNodeWSAddress = endpoint(
+        readNodeAddresses[1],
+        ['wss:', 'ws:'],
+        options.allowInsecure
+      ).href
     }
 
+    this._httpClient = new HTTP(this._readNodeAddress, options)
     this._options = new Options(this._readNodeWSAddress)
-    this._options.setCustomWS(this._wsLibrary)
+      .setAllowInsecure(options.allowInsecure)
+      .setCustomWS(this._wsLibrary)
+
+    if (typeof options.maxMessageBytes !== 'undefined')
+      this._options.setMaxMessageBytes(options.maxMessageBytes)
+
+    if (typeof options.maxEnqueuedMessages !== 'undefined')
+      this._options.setMaxEnqueuedMessages(options.maxEnqueuedMessages)
+
+    if (typeof options.maxPendingCallbacks !== 'undefined')
+      this._options.setMaxPendingCallbacks(options.maxPendingCallbacks)
 
     if (chainName) this._chainName = chainName
+
     if (chainVersion) this._chainVersion = chainVersion
   }
 
   SetDebug(debug) {
     this._options.setDebug(debug)
+
     return this
   }
 
@@ -130,6 +165,9 @@ export default class TCaBCIClient {
    * @return {TCaBCIClient}
    */
   SetSuccessCallback(cb) {
+    if (cb !== null && typeof cb !== 'function')
+      throw new TypeError('Invalid callback')
+
     this._successCb = cb
 
     return this
@@ -140,6 +178,9 @@ export default class TCaBCIClient {
    * @return {TCaBCIClient}
    */
   SetErrorCallback(cb) {
+    if (cb !== null && typeof cb !== 'function')
+      throw new TypeError('Invalid callback')
+
     this._errorCb = cb
 
     return this
@@ -150,6 +191,9 @@ export default class TCaBCIClient {
    * @return {TCaBCIClient}
    */
   SetCloseCallback(cb) {
+    if (cb !== null && typeof cb !== 'function')
+      throw new TypeError('Invalid callback')
+
     this._closeCb = cb
 
     return this
@@ -160,6 +204,9 @@ export default class TCaBCIClient {
    * @return {TCaBCIClient}
    */
   SetListenCallback(cb) {
+    if (cb !== null && typeof cb !== 'function')
+      throw new TypeError('Invalid callback')
+
     this._listenCb = cb
 
     return this
@@ -173,42 +220,55 @@ export default class TCaBCIClient {
     return this._subscribed
   }
 
+  /** @returns {ReadonlyArray<string>} Frozen address copy. */
   get SubscribeAddresses() {
-    return this._subscribedAddresses
+    return Object.freeze([...this._subscribedAddresses])
   }
 
+  /** @returns {Readonly<Record<string, string>>} Frozen proof copy. */
   get SubscribedSignedData() {
-    return this._SubscribedSignedData
+    return Object.freeze({ ...this._SubscribedSignedData })
   }
 
   get Socket() {
     return this._ws
   }
 
+  /**
+   * Stop the old socket and initiate a replacement connection.
+   * @param {number} [code=1000]
+   * @returns {Promise<TCaBCIClient>}
+   */
   async Reconnect(code = 1000) {
-    if (this.IsConnected()) {
-      await this._disconnect(code)
-    }
+    const stopping = this._disconnect(code),
+      generation = this._generation
+
+    await stopping
+
+    if (generation !== this._generation) return this
 
     await this._connect()
 
     return this
   }
 
+  /**
+   * Initiate one shared connection attempt; does not await the OPEN event.
+   * @returns {Promise<TWebSocket>}
+   */
   async Start() {
     return this._connect()
   }
 
   /**
-   * @param {?number} code
-   * @return {Awaited<TCaBCIClient>}
-   * @throws {Error}
+   * Idempotently stop sockets, abort HTTP and release subscription state.
+   * Application callbacks remain registered for reuse; Dispose releases them.
+   * Caller-owned buffers are never zeroed or frozen.
+   * @param {number} [code=1000]
+   * @returns {Promise<TCaBCIClient>}
    */
   async Stop(code = 1000) {
-    if (!this.IsConnected()) {
-      throw new Error(NOT_CONNECTED)
-    }
-
+    this._httpClient.abort()
     await this._disconnect(code)
     this._setConnected(false)
     this._setSubscribed(false)
@@ -216,69 +276,56 @@ export default class TCaBCIClient {
     return this
   }
 
+  /**
+   * Return a detached, frozen status snapshot.
+   * @returns {Readonly<import('./client.js').ClientStatus>}
+   */
   Status() {
-    return {
+    return Object.freeze({
       chain_name: this._chainName,
       chain_version: this._chainVersion,
       connected: this._connected,
       subscribed: this._subscribed
-    }
+    })
   }
 
   /**
-   * @param {Array<string>} addresses
-   * @param {Object} signedData
-   * @param {?Array<string>} txTypes
-   * @return {TCaBCIClient}
-   * @throws {Error}
+   * 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.
+   * @param {readonly string[]} addresses
+   * @param {Readonly<Record<string, string>>} signedData
+   * @param {readonly string[]|null} [txTypes=null]
+   * @returns {TCaBCIClient}
    */
   Subscribe(addresses, signedData, txTypes = null) {
-    if (!Array.isArray(addresses) || addresses.length === 0)
-      throw new Error(INVALID_ARGUMENT_WITH_CS('addresses'))
-
-    if (typeof signedData !== 'object') throw new Error(INVALID_ARGUMENTS)
-
-    if (txTypes && Array.isArray(txTypes)) {
-      if (!Array.isArray(txTypes))
-        throw new Error(INVALID_ARGUMENT_WITH_CS('txTypes'))
-
-      if (txTypes.length > TX_TYPE_LIST.length)
-        throw new Error(INVALID_ARGUMENT_WITH_CS('txTypes'))
-
-      for (let i = 0; i < txTypes.length; i++) {
-        if (!TX_TYPE_LIST.includes(txTypes[i]))
-          throw new Error(INVALID_ARGUMENT_WITH_CS('txType ', txTypes[i]))
-      }
-    }
+    const requested = validateAddresses(addresses),
+      proof = validateSignedData(signedData)
+
+    if (
+      txTypes !== null &&
+      (!Array.isArray(txTypes) ||
+        txTypes.length > TX_TYPE_LIST.length ||
+        txTypes.some((type) => !TX_TYPE_LIST.includes(type)))
+    )
+      throw new Error(INVALID_ARGUMENT_WITH_CS('txTypes'))
 
     if (!this.IsConnected()) throw new Error(NOT_CONNECTED)
 
-    const addrs = [],
-      _signedData = signedData ?? this.SubscribedSignedData
-
-    addrs.push(...addresses)
-
-    if (this.SubscribeAddresses.length > 0) {
-      let newAddress = []
-
-      for (let i = 0; i < addresses.length; i++) {
-        if (this.SubscribeAddresses.indexOf(addresses[i]) === -1) {
-          newAddress.push(addresses[i])
-        }
-      }
-      addrs.push(...newAddress)
-    }
+    const addrs = validateAddresses([
+      ...new Set([...this._subscribedAddresses, ...requested])
+    ])
 
     this._ws.send(
       new Message({
         isWeb: true,
         type: SUBSCRIBEMessage,
         addrs: addrs,
-        signedData: _signedData,
+        signedData: proof,
         txTypes
       }).ToJSON()
     )
-    this._setSubscribeAddresses(addrs, true)._setSubscribeSignedData(signedData)
+    this._setSubscribeAddresses(addrs)._setSubscribeSignedData(proof)
 
     return this
   }
@@ -290,108 +337,122 @@ export default class TCaBCIClient {
     if (!this.IsSubscribed()) {
       throw new Error(NOT_SUBSCRIBED)
     }
-    this._ws.send(
-      new Message({
-        isWeb: true,
-        type: UNSUBSCRIBEMessage,
-        addrs: this.SubscribeAddresses
-      }).ToJSON()
-    )
-    this._setSubscribed(false)
-    this._setSubscribeAddresses([])
-    this._setSubscribeSignedData({})
+
+    try {
+      this._ws.send(
+        new Message({
+          isWeb: true,
+          type: UNSUBSCRIBEMessage,
+          addrs: this.SubscribeAddresses
+        }).ToJSON()
+      )
+    } finally {
+      this._clearSubscription()
+    }
 
     return this
   }
 
   /**
-   * @param {?string} chainName
-   * @param {?string} chainVersion
-   * @return {Promise<{blocks: [], info: {chain_name: null, chain_version: null, hash: *, height: *, txs: *, created_at: *}, total_count: *} | Error>}
-   * @constructor
+   * Read the latest block; query values are URL-encoded.
+   * @param {string|null} [chainName=null]
+   * @param {string|null} [chainVersion=null]
+   * @param {import('./types.js').RequestOptions} [requestOptions={}]
+   * @returns {Promise<Readonly<Awaited<ReturnType<import('./client.js').default['LastBlock']>>>>} Frozen result; nested snapshots are readonly.
    */
-  LastBlock(chainName = null, chainVersion = null) {
-    return this._httpClient
-      .request(
-        `/v1/blocks?chain_name=${chainName ?? this._chainName}&chain_version=${chainVersion ?? this._chainVersion}&limit=1&offset=0`,
-        {
-          method: 'GET'
-        }
-      )
-      .then(res => {
-        return {
-          blocks: [],
-          info: {
-            chainName: chainName,
-            chainVersion: chainVersion,
+  LastBlock(chainName = null, chainVersion = null, requestOptions = {}) {
+    return this._request(
+      `/v1/blocks?chain_name=${encodeURIComponent(chainName ?? this._chainName)}&chain_version=${encodeURIComponent(chainVersion ?? this._chainVersion)}&limit=1&offset=0`,
+      {
+        method: 'GET'
+      },
+      requestOptions
+    )
+      .then((res) => {
+        return Object.freeze({
+          blocks: Object.freeze([]),
+          info: Object.freeze({
+            chainName: chainName ?? this._chainName,
+            chainVersion: chainVersion ?? this._chainVersion,
             hash: res.data.hash,
             height: res.data.height,
             txs: res.data.txs,
-            createdAt: new Date(res.data.inserted_at)
-          },
+            createdAt: new Date(rfc3339Timestamp(res.data.inserted_at))
+          }),
           total_count: res.total_count
-        }
+        })
       })
-      .catch(e => this._httpClient.handleError(e, new Error(BLOCK_NOT_FOUND)))
+      .catch((e) => this._httpClient.handleError(e, new Error(BLOCK_NOT_FOUND)))
   }
 
   /**
+   * Read a transaction. Signature headers are never followed across redirects.
    * @param {string} id
    * @param {string} signature
-   * @return {Promise<*>}
+   * @param {import('./types.js').RequestOptions} [requestOptions={}]
+   * @returns {Promise<Readonly<{tx: Readonly<Transaction>}>>} Frozen result; nested snapshots are readonly.
    */
-  Tx(id, signature) {
-    if (!id || typeof id !== 'string') {
+  Tx(id, signature, requestOptions = {}) {
+    if (
+      !id ||
+      id === '.' ||
+      id === '..' ||
+      typeof id !== 'string' ||
+      typeof signature !== 'string' ||
+      !signature.length
+    ) {
       return Promise.reject(new Error(INVALID_ARGUMENTS))
     }
 
-    return this._httpClient
-      .request(`/v1/tx/${id}`, {
+    return this._request(
+      `/v1/tx/${encodeURIComponent(id)}`,
+      {
         method: 'GET',
         headers: { 'X-Signature': signature }
-      })
-      .then(res => {
+      },
+      requestOptions
+    )
+      .then((res) => {
         const { transaction, error } = Transaction.FromObject(res.data)
+
         if (error) return Promise.reject(error)
 
-        return { tx: transaction }
+        return Object.freeze({ tx: transaction })
       })
-      .catch(e => this._httpClient.handleError(e))
+      .catch((e) => this._httpClient.handleError(e))
   }
 
   /**
-   * @param {?Array<string>} recipientAddrs
-   * @param {?Array<string>} senderAddrs
-   * @param {?Object} signedData
-   * @param {?string} typ
-   * @param {?Array<string>} types
-   * @param {?string} chainName
-   * @param {?string} chainVersion
-   * @return {Promise<{
-   *           chain_name: string,
-   *           chain_version: string,
-   *           first_block_height: number,
-   *           first_transaction: Transaction,
-   *           last_block_height: number,
-   *           last_transaction: Transaction,
-   *           total_count: number,
-   *         }>}
+   * Read transaction data with cancellation and a total request deadline.
+   * @param {import('./client.js').TxQuery} query
+   * @param {import('./types.js').RequestOptions} [requestOptions={}]
+   * @returns {Promise<Readonly<Awaited<ReturnType<import('./client.js').default['TxSummary']>>>>} Frozen result; nested snapshots are readonly.
    */
-  TxSummary({
-    recipientAddrs,
-    senderAddrs,
-    signedData,
-    typ,
-    types = null,
-    chainName = null,
-    chainVersion = null
-  }) {
+  TxSummary(
+    {
+      recipientAddrs,
+      senderAddrs,
+      signedData,
+      typ,
+      types = null,
+      chainName = null,
+      chainVersion = null
+    },
+    requestOptions = {}
+  ) {
     if (!recipientAddrs && !senderAddrs) {
       return Promise.reject(new Error(INVALID_ARGUMENTS))
     }
 
-    return this._httpClient
-      .request('/v1/tx_summary', {
+    if (recipientAddrs) recipientAddrs = validateAddresses(recipientAddrs)
+
+    if (senderAddrs) senderAddrs = validateAddresses(senderAddrs)
+
+    if (signedData) signedData = validateSignedData(signedData)
+
+    return this._request(
+      '/v1/tx_summary',
+      {
         method: 'POST',
         body: JSON.stringify({
           chain_name: chainName ?? this._chainName,
@@ -401,15 +462,19 @@ export default class TCaBCIClient {
           signed_addrs: signedData,
           ...(types ? { types: types } : { typ: typ })
         })
-      })
-      .then(res => {
+      },
+      requestOptions
+    )
+      .then((res) => {
         let firstTransaction, lastTransaction
 
         if (res.data.first_transaction) {
           const { transaction, error } = Transaction.FromObject(
             res.data.first_transaction
           )
+
           if (error) return Promise.reject(error)
+
           firstTransaction = transaction
         }
 
@@ -417,11 +482,13 @@ export default class TCaBCIClient {
           const { transaction, error: errorTwo } = Transaction.FromObject(
             res.data.last_transaction
           )
+
           if (errorTwo) return Promise.reject(errorTwo)
+
           lastTransaction = transaction
         }
 
-        return {
+        return Object.freeze({
           chain_name: res.data.chain_name,
           chain_version: res.data.chain_version,
           first_block_height: res.data.first_block_height,
@@ -429,50 +496,47 @@ export default class TCaBCIClient {
           last_block_height: res.data.last_block_height,
           last_transaction: lastTransaction,
           total_count: res.total_count
-        }
+        })
       })
-      .catch(e => this._httpClient.handleError(e))
+      .catch((e) => this._httpClient.handleError(e))
   }
 
   /**
-   * @param {string} heightOperator
-   * @param {number} height
-   * @param {?number} maxHeight
-   * @param {?number} lastOrder
-   * @param {?Array<string>} recipientAddrs
-   * @param {?Array<string>} senderAddrs
-   * @param {?Object} signedData
-   * @param {?Array<string>} hashes
-   * @param {string} typ
-   * @param {?Array<string>} types
-   * @param {number} limit
-   * @param {number} offset
-   * @param {string} orderField
-   * @param {string} orderBy
-   * @param {?string} chainName
-   * @param {?string} chainVersion
-   * @return {Promise<{txs: Transaction[], total_count: number}>}
+   * Read transaction data with cancellation and a total request deadline.
+   * @param {import('./client.js').TxSearchQuery} query
+   * @param {import('./types.js').RequestOptions} [requestOptions={}]
+   * @returns {Promise<Readonly<Awaited<ReturnType<import('./client.js').default['TxSearch']>>>>} Frozen result; nested snapshots are readonly.
    */
-  TxSearch({
-    heightOperator,
-    height,
-    maxHeight,
-    lastOrder,
-    recipientAddrs,
-    senderAddrs,
-    signedData,
-    hashes,
-    typ,
-    types,
-    limit,
-    offset,
-    orderField,
-    orderBy,
-    chainName = null,
-    chainVersion = null
-  }) {
-    return this._httpClient
-      .request('/v1/tx_search/p', {
+  TxSearch(
+    {
+      heightOperator,
+      height,
+      maxHeight,
+      lastOrder,
+      recipientAddrs,
+      senderAddrs,
+      signedData,
+      hashes,
+      typ,
+      types,
+      limit,
+      offset,
+      orderField,
+      orderBy,
+      chainName = null,
+      chainVersion = null
+    },
+    requestOptions = {}
+  ) {
+    if (recipientAddrs) recipientAddrs = validateAddresses(recipientAddrs)
+
+    if (senderAddrs) senderAddrs = validateAddresses(senderAddrs)
+
+    if (signedData) signedData = validateSignedData(signedData)
+
+    return this._request(
+      '/v1/tx_search/p',
+      {
         method: 'POST',
         body: JSON.stringify({
           chain_name: chainName ?? this._chainName,
@@ -490,45 +554,38 @@ export default class TCaBCIClient {
           ...(orderBy ? { order_by: orderBy } : {}),
           ...(types ? { types: types } : typ ? { typ: typ } : {})
         })
-      })
-      .then(res => {
+      },
+      requestOptions
+    )
+      .then((res) => {
         const data = []
 
         for (const _data of res.data) {
           const { transaction, error } = Transaction.FromObject(_data)
+
           if (error) return Promise.reject(error)
+
           data.push(transaction)
         }
 
-        return {
-          txs: data,
+        return Object.freeze({
+          txs: Object.freeze(data),
           total_count: res.total_count
-        }
+        })
       })
-      .catch(e => this._httpClient.handleError(e))
+      .catch((e) => this._httpClient.handleError(e))
   }
 
   /**
-   * @param {string} id
-   * @param {number} version
-   * @param {string} type
-   * @param {string} data
-   * @param {string} sender_addr
-   * @param {string} recipient_addr
-   * @param {string} sign
-   * @param {number} fee
-   * @return {Promise<any>}
+   * Publish once: automatic retries are disabled to avoid duplicate writes.
+   * @param {import('./client.js').BroadcastInput} input
+   * @param {import('./types.js').RequestOptions} [requestOptions={}]
+   * @returns {Promise<Readonly<{data: import('./types.js').JSONValue}>>} Frozen result; nested snapshots are readonly.
    */
-  BroadcastCommit({
-    id,
-    version,
-    type,
-    data,
-    sender_addr,
-    recipient_addr,
-    sign,
-    fee
-  }) {
+  BroadcastCommit(
+    { id, version, type, data, sender_addr, recipient_addr, sign, fee },
+    requestOptions = {}
+  ) {
     return this.broadcast(
       {
         id,
@@ -541,35 +598,32 @@ export default class TCaBCIClient {
         fee
       },
       false,
-      true
+      true,
+      requestOptions
     )
   }
 
   /**
-   * @param {string} id
-   * @param {number} version
-   * @param {string} type
-   * @param {string} data
-   * @param {?string} additional_data
-   * @param {?string} cipher_data
-   * @param {string} sender_addr
-   * @param {string} recipient_addr
-   * @param {string} sign
-   * @param {number} fee
-   * @return {Promise<any>}
+   * Publish once: automatic retries are disabled to avoid duplicate writes.
+   * @param {import('./client.js').BroadcastInput} input
+   * @param {import('./types.js').RequestOptions} [requestOptions={}]
+   * @returns {Promise<Readonly<{data: import('./types.js').JSONValue}>>} Frozen result; nested snapshots are readonly.
    */
-  BroadcastSync({
-    id,
-    version,
-    type,
-    data,
-    additional_data = null,
-    cipher_data = null,
-    sender_addr,
-    recipient_addr,
-    sign,
-    fee
-  }) {
+  BroadcastSync(
+    {
+      id,
+      version,
+      type,
+      data,
+      additional_data = null,
+      cipher_data = null,
+      sender_addr,
+      recipient_addr,
+      sign,
+      fee
+    },
+    requestOptions = {}
+  ) {
     return this.broadcast(
       {
         id,
@@ -584,35 +638,32 @@ export default class TCaBCIClient {
         fee
       },
       true,
-      false
+      false,
+      requestOptions
     )
   }
 
   /**
-   * @param {string} id
-   * @param {number} version
-   * @param {string} type
-   * @param {string} data
-   * @param {?string} additional_data
-   * @param {?string} cipher_data
-   * @param {string} sender_addr
-   * @param {string} recipient_addr
-   * @param {string} sign
-   * @param {number} fee
-   * @return {Promise<any>}
+   * Publish once: automatic retries are disabled to avoid duplicate writes.
+   * @param {import('./client.js').BroadcastInput} input
+   * @param {import('./types.js').RequestOptions} [requestOptions={}]
+   * @returns {Promise<Readonly<{data: import('./types.js').JSONValue}>>} Frozen result; nested snapshots are readonly.
    */
-  Broadcast({
-    id,
-    version,
-    type,
-    data,
-    additional_data = null,
-    cipher_data = null,
-    sender_addr,
-    recipient_addr,
-    sign,
-    fee
-  }) {
+  Broadcast(
+    {
+      id,
+      version,
+      type,
+      data,
+      additional_data = null,
+      cipher_data = null,
+      sender_addr,
+      recipient_addr,
+      sign,
+      fee
+    },
+    requestOptions = {}
+  ) {
     return this.broadcast(
       {
         id,
@@ -627,10 +678,19 @@ export default class TCaBCIClient {
         fee
       },
       false,
-      false
+      false,
+      requestOptions
     )
   }
 
+  /**
+   * Internal/public legacy broadcast entry; never retries a write.
+   * @param {import('./client.js').BroadcastInput} input
+   * @param {boolean} [sync=false]
+   * @param {boolean} [commit=false]
+   * @param {import('./types.js').RequestOptions} [requestOptions={}]
+   * @returns {Promise<Readonly<{data: import('./types.js').JSONValue}>>} Frozen result; nested snapshots are readonly.
+   */
   broadcast(
     {
       id,
@@ -645,14 +705,30 @@ export default class TCaBCIClient {
       fee
     },
     sync = false,
-    commit = false
+    commit = false,
+    requestOptions = {}
   ) {
     if (!TX_TYPE_LIST.includes(type)) {
       throw new Error(TRANSACTION_TYPE_NOT_VALID)
     }
 
-    return this._httpClient
-      .request(commit ? '/v1/tx/commit' : sync ? '/v1/tx/sync' : '/v1/tx', {
+    validateAddresses([sender_addr, recipient_addr])
+
+    if (
+      typeof id !== 'string' ||
+      !id.length ||
+      typeof sign !== 'string' ||
+      !sign.length ||
+      !Number.isSafeInteger(version) ||
+      version < 0 ||
+      !Number.isFinite(fee) ||
+      fee < 0
+    )
+      throw new Error(INVALID_ARGUMENTS)
+
+    return this._request(
+      commit ? '/v1/tx/commit' : sync ? '/v1/tx/sync' : '/v1/tx',
+      {
         method: 'POST',
         body: JSON.stringify({
           id,
@@ -666,11 +742,13 @@ export default class TCaBCIClient {
           sign,
           fee
         })
+      },
+      requestOptions
+    )
+      .then((res) => {
+        return Object.freeze({ data: res.data })
       })
-      .then(res => {
-        return { data: res.data }
-      })
-      .catch(e =>
+      .catch((e) =>
         this._httpClient.handleError(e, {
           400: new Error(TRANSACTION_NOT_BROADCAST)
         })
@@ -678,86 +756,144 @@ export default class TCaBCIClient {
   }
 
   /**
-   * @param {Array<string>} addresses
-   * @param {Object} signedData
-   * @param {?number} maxHeight
-   * @param {?string} chainName
-   * @param {?string} chainVersion
-   * @return {Promise<*>}
-   * @constructor
+   * Read a bounded address batch (1..251 entries; 1..2048 chars per address).
+   * @param {readonly string[]} [addresses=[]]
+   * @param {Readonly<Record<string, string>>} [signedData={}]
+   * @param {number|null} [maxHeight=null]
+   * @param {string|null} [chainName=null]
+   * @param {string|null} [chainVersion=null]
+   * @param {import('./types.js').RequestOptions} [requestOptions={}]
+   * @returns {Promise<import('./types.js').JSONValue>} Recursively readonly JSON snapshot.
    */
   Bulk(
     addresses = [],
     signedData = {},
     maxHeight = null,
     chainName = null,
-    chainVersion = null
+    chainVersion = null,
+    requestOptions = {}
   ) {
-    return this._httpClient.request('/v1/bulk_tx', {
-      method: 'POST',
-      body: JSON.stringify({
-        chain_name: chainName ?? this._chainName,
-        chain_version: chainVersion ?? this._chainVersion,
-        addresses: addresses,
-        signed_addrs: signedData,
-        ...(maxHeight ? { max_height: maxHeight } : {})
-      })
-    })
+    addresses = validateAddresses(addresses)
+    signedData = validateSignedData(signedData)
+
+    return this._request(
+      '/v1/bulk_tx',
+      {
+        method: 'POST',
+        body: JSON.stringify({
+          chain_name: chainName ?? this._chainName,
+          chain_version: chainVersion ?? this._chainVersion,
+          addresses: addresses,
+          signed_addrs: signedData,
+          ...(maxHeight ? { max_height: maxHeight } : {})
+        })
+      },
+      requestOptions
+    )
   }
 
   /**
    * @return {Promise<TWebSocket>}
    */
   async _connect() {
-    if (this.IsConnected()) {
-      return Promise.reject(new Error(ALREADY_CONNECTED))
-    }
+    if (this.IsConnected()) throw new Error(ALREADY_CONNECTED)
+
+    if (this._startPromise) return this._startPromise
+
+    if (this._ws) return this._ws
 
-    this._ws = new TWebSocket(this._options)
+    const generation = this._generation,
+      ws = new TWebSocket(this._options)
+
+    this._ws = ws
+
+    const current = () => generation === this._generation && this._ws === ws
+
+    ws.addErrorListener((e) => {
+      if (!current()) return
 
-    this._ws.addErrorListener(e => {
       this._setConnected(false)
-      this._setSubscribed(false)
-      this._setSubscribeAddresses([], false)
-      this._setSubscribeSignedData({})
+      this._clearSubscription()
       this._callErrorCallback(e)
     })
+    ws.addOpenListener((e) => {
+      if (!current()) return
 
-    this._ws.addOpenListener(e => {
       this._setConnected(true)
       this._callSuccessCallback(e)
     })
-
-    this._ws.addMessageListener(message => {
-      this._callListenCallback(message.data)
+    ws.addMessageListener((message) => {
+      if (current()) this._callListenCallback(message.data)
     })
+    ws.addCloseListener((e) => {
+      if (!current()) return
 
-    this._ws.addCloseListener(e => {
       this._setConnected(false)
-      this._setSubscribed(false)
-      this._setSubscribeAddresses([], false)
-      this._setSubscribeSignedData({})
+      this._clearSubscription()
+
+      if (!ws.active) this._ws = null
+
       this._callCloseCallback(e)
     })
 
-    return this._ws.connect()
+    const start = ws.connect()
+
+    this._startPromise = start
+
+    try {
+      return await start
+    } catch {
+      if (current()) await this._disconnect()
+
+      throw new Error('Connection failed')
+    } finally {
+      if (this._startPromise === start) this._startPromise = null
+    }
   }
 
-  /**
-   * @param {?number} code
-   * @return {Promise<TCaBCIClient>}
-   */
   async _disconnect(code = 1000) {
-    if (this.IsConnected()) {
-      await this._ws.disconnect(code)
+    code = closeCode(code)
 
-      this._setConnected(false)
-      this._setSubscribed(false)
-    }
+    const ws = this._ws
+
+    this._generation++
+    this._ws = null
+    this._startPromise = null
+    this._setConnected(false)
+    this._clearSubscription()
+    await ws?.disconnect(code)
 
     return this
   }
 
+  _clearSubscription() {
+    this._setSubscribed(false)
+    this._setSubscribeAddresses([])
+    this._setSubscribeSignedData({})
+  }
+
+  /**
+   * Stop all work and release application callback references.
+   * @returns {Promise<TCaBCIClient>}
+   */
+  async Dispose() {
+    await this.Stop()
+    this._successCb = null
+    this._errorCb = null
+    this._closeCb = null
+    this._listenCb = null
+
+    return this
+  }
+
+  _request(uri, req, options = {}) {
+    const readOnly =
+      req.method === 'GET' ||
+      ['/v1/tx_summary', '/v1/tx_search/p', '/v1/bulk_tx'].includes(uri)
+
+    return this._httpClient.request(uri, req, { ...options, retry: readOnly })
+  }
+
   _setSubscribed(value) {
     this._subscribed = value
   }
@@ -773,11 +909,14 @@ export default class TCaBCIClient {
    */
   _setSubscribeAddresses(addresses, push = false) {
     if (push) {
-      this._subscribedAddresses.push(...addresses)
+      this._subscribedAddresses = [
+        ...new Set([...this._subscribedAddresses, ...addresses])
+      ]
 
       return this
     }
-    this._subscribedAddresses = addresses
+
+    this._subscribedAddresses = [...addresses]
 
     return this
   }
@@ -787,7 +926,7 @@ export default class TCaBCIClient {
    * @return {TCaBCIClient}
    */
   _setSubscribeSignedData(signedData) {
-    this._SubscribedSignedData = signedData
+    this._SubscribedSignedData = { ...signedData }
 
     return this
   }
@@ -808,41 +947,52 @@ export default class TCaBCIClient {
     let msg
 
     const { transaction, error: e1 } = Transaction.FromJSON(message)
+
     if (e1) {
       const { message: _msg, error: e2 } = Message.FromJSON(message)
+
       if (e2) {
         this._callErrorCallback(e2)
+
         return
       }
 
-      switch (_msg.type) {
+      switch (_msg.Type) {
         case MBlock:
-          msg = Block.FromObject(_msg.data)
+          msg = Block.FromObject(_msg.Data)
+
           if (msg.error) {
             this._callErrorCallback(msg.error)
+
             return
           }
 
           if (this._listenCb) this._listenCb(msg.block, null, null)
+
           break
         case MTransaction:
-          msg = Transaction.FromObject(_msg.data)
+          msg = Transaction.FromObject(_msg.Data)
+
           if (msg.error) {
             this._callErrorCallback(msg.error)
+
             return
           }
 
           if (this._listenCb) this._listenCb(null, msg.transaction, null)
+
           break
         case Subscription:
-          if (message.state === OK) {
+          if (_msg.State === OK) {
             this._setSubscribed(true)
           } else {
-            this._setSubscribed(false)
+            this._clearSubscription()
           }
+
           break
         default:
           if (this._listenCb) this._listenCb(null, null, _msg)
+
           break
       }
     } else {