@electrum-cash/network/dist/index.mjs.map

@electrum-cash/network is a lightweight JavaScript library that lets you connect with one or more Electrum servers.

{"version":3,"file":"index.mjs","names":[],"sources":["../source/electrum-protocol.ts","../source/rpc-interfaces.ts","../source/enums.ts","../source/interfaces.ts","../source/electrum-connection.ts","../source/constants.ts","../source/electrum-client.ts"],"sourcesContent":["import type { RPCParameter } from './rpc-interfaces.ts';\n\n/**\n * Grouping of utilities that simplifies implementation of the Electrum protocol.\n *\n * @ignore\n */\nexport class ElectrumProtocol\n{\n\t/**\n\t * Helper function that builds an Electrum request object.\n\t *\n\t * @param method     - method to call.\n\t * @param parameters - method parameters for the call.\n\t * @param requestId  - unique string or number referencing this request.\n\t *\n\t * @returns a properly formatted Electrum request string.\n\t */\n\tstatic buildRequestObject(method: string, parameters: RPCParameter[], requestId: string | number): string\n\t{\n\t\t// Return the formatted request object.\n\t\t// NOTE: Electrum either uses JsonRPC strictly or loosely.\n\t\t//       If we specify protocol identifier without being 100% compliant, we risk being disconnected/blacklisted.\n\t\t//       For this reason, we omit the protocol identifier to avoid issues.\n\t\treturn JSON.stringify({ method: method, params: parameters, id: requestId });\n\t}\n\n\t/**\n\t * Constant used to verify if a provided string is a valid version number.\n\t *\n\t * @returns a regular expression that matches valid version numbers.\n\t */\n\tstatic get versionRegexp(): RegExp\n\t{\n\t\treturn /^\\d+(\\.\\d+)+$/;\n\t}\n\n\t/**\n\t * Constant used to separate statements/messages in a stream of data.\n\t *\n\t * @returns the delimiter used by Electrum to separate statements.\n\t */\n\tstatic get statementDelimiter(): string\n\t{\n\t\treturn '\\n';\n\t}\n}\n","// Acceptable parameter types for RPC messages\nexport type RPCParameter = string | number | boolean | object | null;\n\n// Acceptable identifier types for RCP messages.\nexport type RCPIdentifier = number | string | null;\n\n// The base type for all RPC messages\nexport interface RPCBase\n{\n\tjsonrpc: string;\n}\n\n// An RPC message that sends a notification requiring no response\nexport interface RPCNotification extends RPCBase\n{\n\tmethod: string;\n\tparams?: RPCParameter[];\n}\n\n// An RPC message that sends a request requiring a response\nexport interface RPCRequest extends RPCBase\n{\n\tid: RCPIdentifier;\n\tmethod: string;\n\tparams?: RPCParameter[];\n}\n\n// An RPC message that returns the response to a successful request\nexport interface RPCStatement extends RPCBase\n{\n\tid: RCPIdentifier;\n\tresult: string;\n}\n\nexport interface RPCError\n{\n\tcode: number;\n\tmessage: string;\n\tdata?: unknown;\n}\n\n// An RPC message that returns the error to an unsuccessful request\nexport interface RPCErrorResponse extends RPCBase\n{\n\tid: RCPIdentifier;\n\terror: RPCError;\n}\n\n// A response to a request is either a statement (successful) or an error (unsuccessful)\nexport type RPCResponse = RPCErrorResponse | RPCStatement | RPCNotification;\n\n// RPC messages are notifications, requests, or responses\nexport type RPCMessage = RPCNotification | RPCRequest | RPCResponse;\n\n// Requests and responses can also be sent in batches\nexport type RPCResponseBatch = RPCResponse[];\nexport type RPCRequestBatch = RPCRequest[];\n\nexport const isRPCErrorResponse = function(message: RPCBase): message is RPCErrorResponse\n{\n\treturn 'id' in message && 'error' in message;\n};\n\nexport const isRPCStatement = function(message: RPCBase): message is RPCStatement\n{\n\treturn 'id' in message && 'result' in message;\n};\n\nexport const isRPCNotification = function(message: RPCBase): message is RPCNotification\n{\n\treturn !('id' in message) && 'method' in message;\n};\n\nexport const isRPCRequest = function(message: RPCBase): message is RPCRequest\n{\n\treturn 'id' in message && 'method' in message;\n};\n","/**\n * Enum that denotes the connection status of an ElectrumConnection.\n * @enum {number}\n * @property {0} DISCONNECTED    The connection is disconnected.\n * @property {1} AVAILABLE       The connection is connected.\n * @property {2} DISCONNECTING   The connection is disconnecting.\n * @property {3} CONNECTING      The connection is connecting.\n * @property {4} RECONNECTING    The connection is restarting.\n */\nexport enum ConnectionStatus\n{\n\tDISCONNECTED = 0,\n\tCONNECTED = 1,\n\tDISCONNECTING = 2,\n\tCONNECTING = 3,\n\tRECONNECTING = 4,\n}\n","import type { RPCError, RPCParameter, RPCResponse, RPCNotification } from './rpc-interfaces';\nimport type { EventEmitter } from 'eventemitter3';\n\n/**\n * Optional settings that change the default behavior of the network connection.\n */\nexport interface ElectrumNetworkOptions\n{\n\t/** If set to true, numbers that can safely be parsed as integers will be `BigInt` rather than `Number`. */\n\tuseBigInt?: boolean;\n\n\t/** When connected, send a keep-alive Ping message this often. */\n\tsendKeepAliveIntervalInMilliSeconds?: number;\n\n\t/** When disconnected, attempt to reconnect after this amount of time. */\n\treconnectAfterMilliSeconds?: number;\n\n\t/** After every send, verify that we have received data after this amount of time. */\n\tverifyConnectionTimeoutInMilliSeconds?: number;\n\n\t/** Turn off automatic handling of browser visibility, which disconnects when application is not visible to be consistent across browsers.  */\n\tdisableBrowserVisibilityHandling?: boolean;\n\n\t/** Turn off automatic handling of browser connectivity. */\n\tdisableBrowserConnectivityHandling?: boolean;\n}\n\n/**\n * List of events emitted by the ElectrumSocket.\n * @event\n * @ignore\n */\nexport interface ElectrumSocketEvents\n{\n\t/**\n\t * Emitted when data has been received over the socket.\n\t * @eventProperty\n\t */\n\t'data': [ string ];\n\n\t/**\n\t * Emitted when a socket connects.\n\t * @eventProperty\n\t */\n\t'connected': [];\n\n\t/**\n\t * Emitted when a socket disconnects.\n\t * @eventProperty\n\t */\n\t'disconnected': [];\n\n\t/**\n\t * Emitted when the socket has failed in some way.\n\t * @eventProperty\n\t */\n\t'error': [ Error ];\n}\n\n/**\n * Abstract socket used when communicating with Electrum servers.\n */\nexport interface ElectrumSocket extends EventEmitter<ElectrumSocketEvents>, ElectrumSocketEvents\n{\n\t/**\n\t * Utility function to provide a human accessible host identifier.\n\t */\n\tget hostIdentifier(): string;\n\n\t/**\n\t * Fully qualified domain name or IP address of the host\n\t */\n\thost: string;\n\n\t/**\n\t * Network port for the host to connect to, defaults to the standard TLS port\n\t */\n\tport: number;\n\n\t/**\n\t * If false, uses an unencrypted connection instead of the default on TLS\n\t */\n\tencrypted: boolean;\n\n\t/**\n\t * If no connection is established after `timeout` ms, the connection is terminated\n\t */\n\ttimeout: number;\n\n\t/**\n\t * Connects to an Electrum server using the socket.\n\t */\n\tconnect(): void;\n\n\t/**\n\t * Disconnects from the Electrum server from the socket.\n\t */\n\tdisconnect(): void;\n\n\t/**\n\t * Write data to the Electrum server on the socket.\n\t *\n\t * @param data     - Data to be written to the socket\n\t * @param callback - Callback function to be called when the write has completed\n\t */\n\twrite(data: Uint8Array | string, callback?: (err?: Error) => void): boolean;\n}\n\n/**\n * @ignore\n */\nexport interface VersionRejected\n{\n\terror: RPCError;\n}\n\n/**\n * @ignore\n */\nexport interface VersionNegotiated\n{\n\tsoftware: string;\n\tprotocol: string;\n}\n\n/**\n * @ignore\n */\nexport type VersionNegotiationResponse = VersionNegotiated | VersionRejected;\n\n/**\n * List of events emitted by the ElectrumConnection.\n * @event\n * @ignore\n */\nexport interface ElectrumConnectionEvents\n{\n\t/**\n\t * Emitted when any data has been received over the network.\n\t * @eventProperty\n\t */\n\t'received': [];\n\n\t/**\n\t * Emitted when a complete electrum message has been received over the network.\n\t * @eventProperty\n\t */\n\t'response': [ RPCResponse ];\n\n\t/**\n\t * Emitted when the connection has completed version negotiation.\n\t * @eventProperty\n\t */\n\t'version': [ VersionNegotiationResponse ];\n\n\t/**\n\t * Emitted when a network connection is initiated.\n\t * @eventProperty\n\t */\n\t'connecting': [];\n\n\t/**\n\t * Emitted when a network connection is successful.\n\t * @eventProperty\n\t */\n\t'connected': [];\n\n\t/**\n\t * Emitted when a network disconnection is initiated.\n\t * @eventProperty\n\t */\n\t'disconnecting': [];\n\n\t/**\n\t * Emitted when a network disconnection is successful.\n\t * @eventProperty\n\t */\n\t'disconnected': [];\n\n\t/**\n\t * Emitted when a network connect attempts to automatically reconnect.\n\t * @eventProperty\n\t */\n\t'reconnecting': [];\n\n\t/**\n\t * Emitted when the network has failed in some way.\n\t * @eventProperty\n\t */\n\t'error': [ Error ];\n}\n\n/**\n * List of events emitted by the ElectrumClient.\n * @event\n * @ignore\n */\nexport interface ElectrumClientEvents\n{\n\t/**\n\t * Emitted when an electrum subscription statement has been received over the network.\n\t * @eventProperty\n\t */\n\t'notification': [ RPCNotification ];\n\n\t/**\n\t * Emitted when a network connection is initiated.\n\t * @eventProperty\n\t */\n\t'connecting': [];\n\n\t/**\n\t * Emitted when a network connection is successful.\n\t * @eventProperty\n\t */\n\t'connected': [];\n\n\t/**\n\t * Emitted when a network disconnection is initiated.\n\t * @eventProperty\n\t */\n\t'disconnecting': [];\n\n\t/**\n\t * Emitted when a network disconnection is successful.\n\t * @eventProperty\n\t */\n\t'disconnected': [];\n\n\t/**\n\t * Emitted when a network connect attempts to automatically reconnect.\n\t * @eventProperty\n\t */\n\t'reconnecting': [];\n\n\t/**\n\t * Emitted when the network has failed in some way.\n\t * @eventProperty\n\t */\n\t'error': [ Error ];\n}\n\n/**\n * A list of possible responses to requests.\n * @ignore\n */\nexport type RequestResponse = RPCParameter | RPCParameter[];\n\n/**\n * Request resolvers are used to process the response of a request. This takes either\n * an error object or any stringified data, while the other parameter is omitted.\n * @ignore\n */\nexport type RequestResolver = (error?: Error, data?: string) => void;\n\n/**\n * Typing for promise resolution.\n * @ignore\n */\nexport type ResolveFunction<T> = (value: T | PromiseLike<T>) => void;\n\n/**\n * Typing for promise rejection.\n * @ignore\n */\nexport type RejectFunction = (reason?: unknown) => void;\n\n/**\n * @ignore\n */\nexport const isVersionRejected = function(object: VersionNegotiationResponse): object is VersionRejected\n{\n\treturn 'error' in object;\n};\n\n/**\n * @ignore\n */\nexport const isVersionNegotiated = function(object: VersionNegotiationResponse): object is VersionNegotiated\n{\n\treturn 'software' in object && 'protocol' in object;\n};\n","import debug from '@electrum-cash/debug-logs';\nimport { ElectrumWebSocket } from '@electrum-cash/web-socket';\nimport { ElectrumProtocol } from './electrum-protocol.ts';\nimport { isRPCNotification, isRPCErrorResponse } from './rpc-interfaces.ts';\nimport { EventEmitter } from 'eventemitter3';\nimport { ConnectionStatus } from './enums.ts';\nimport { parse, parseNumberAndBigInt } from 'lossless-json';\nimport { isVersionRejected } from './interfaces.ts';\nimport type { ElectrumNetworkOptions, ElectrumConnectionEvents, ElectrumSocket, ResolveFunction, RejectFunction, VersionNegotiationResponse } from './interfaces.ts';\nimport type { RPCResponse } from './rpc-interfaces.ts';\n\n/**\n * Wrapper around TLS/WSS sockets that gracefully separates a network stream into Electrum protocol messages.\n */\nexport class ElectrumConnection extends EventEmitter<ElectrumConnectionEvents>\n{\n\t// Initialize the connected flag to false to indicate that there is no connection\n\tpublic status: ConnectionStatus = ConnectionStatus.DISCONNECTED;\n\n\t// Declare empty timestamps\n\tprivate lastReceivedTimestamp: number;\n\n\t// Declare an empty socket.\n\tprivate socket: ElectrumSocket;\n\n\t// Declare timers for keep-alive pings and reconnection\n\tprivate keepAliveTimer?: number;\n\tprivate reconnectTimer?: number;\n\n\t// Initialize an empty array of connection verification timers.\n\tprivate verifications: Array<number> = [];\n\n\t// Initialize messageBuffer to an empty string\n\tprivate messageBuffer = '';\n\n\t/**\n\t * Sets up network configuration for an Electrum client connection.\n\t *\n\t * @param application       - your application name, used to identify to the electrum host.\n\t * @param version           - protocol version to use with the host.\n\t * @param socketOrHostname  - pre-configured electrum socket or fully qualified domain name or IP number of the host\n\t * @param options           - ...\n\t *\n\t * @throws {Error} if `version` is not a valid version string.\n\t */\n\tconstructor(\n\t\tprivate application: string,\n\t\tprivate version: string,\n\t\tprivate socketOrHostname: ElectrumSocket | string,\n\t\tprivate options: ElectrumNetworkOptions,\n\t)\n\t{\n\t\t// Initialize the event emitter.\n\t\tsuper();\n\n\t\t// Check if the provided version is a valid version number.\n\t\tif(!ElectrumProtocol.versionRegexp.test(version))\n\t\t{\n\t\t\t// Throw an error since the version number was not valid.\n\t\t\tthrow(new Error(`Provided version string (${version}) is not a valid protocol version number.`));\n\t\t}\n\n\t\t// If a hostname was provided..\n\t\tif(typeof socketOrHostname === 'string')\n\t\t{\n\t\t\t// Use a web socket with default parameters.\n\t\t\tthis.socket = new ElectrumWebSocket(socketOrHostname);\n\t\t}\n\t\telse\n\t\t{\n\t\t\t// Use the provided socket.\n\t\t\tthis.socket = socketOrHostname;\n\t\t}\n\n\t\t// Set up handlers for connection and disconnection.\n\t\tthis.socket.on('connected', this.onSocketConnect.bind(this));\n\t\tthis.socket.on('disconnected', this.onSocketDisconnect.bind(this));\n\n\t\t// Set up handler for incoming data.\n\t\tthis.socket.on('data', this.parseMessageChunk.bind(this));\n\n\t\t// Handle visibility changes when run in a browser environment (if not explicitly disabled).\n\t\tif(typeof document !== 'undefined' && !this.options.disableBrowserVisibilityHandling)\n\t\t{\n\t\t\tdocument.addEventListener('visibilitychange', this.handleVisibilityChange.bind(this));\n\t\t}\n\n\t\t// Handle network connection changes when run in a browser environment (if not explicitly disabled).\n\t\tif(typeof window !== 'undefined' && !this.options.disableBrowserConnectivityHandling)\n\t\t{\n\t\t\twindow.addEventListener('online', this.handleNetworkChange.bind(this));\n\t\t\twindow.addEventListener('offline', this.handleNetworkChange.bind(this));\n\t\t}\n\t}\n\n\t// Expose hostIdentifier from the socket.\n\tget hostIdentifier(): string\n\t{\n\t\treturn this.socket.hostIdentifier;\n\t}\n\n\t// Expose port from the socket.\n\tget encrypted(): boolean\n\t{\n\t\treturn this.socket.encrypted;\n\t}\n\n\t/**\n\t * Assembles incoming data into statements and hands them off to the message parser.\n\t *\n\t * @param data - data to append to the current message buffer, as a string.\n\t *\n\t * @throws {SyntaxError} if the passed statement parts are not valid JSON.\n\t */\n\tparseMessageChunk(data: string): void\n\t{\n\t\t// Update the timestamp for when we last received data.\n\t\tthis.lastReceivedTimestamp = Date.now();\n\n\t\t// Emit a notification indicating that the connection has received data.\n\t\tthis.emit('received');\n\n\t\t// Clear and remove all verification timers.\n\t\tthis.verifications.forEach((timer) => clearTimeout(timer));\n\t\tthis.verifications.length = 0;\n\n\t\t// Add the message to the current message buffer.\n\t\tthis.messageBuffer += data;\n\n\t\t// Check if the new message buffer contains the statement delimiter.\n\t\twhile(this.messageBuffer.includes(ElectrumProtocol.statementDelimiter))\n\t\t{\n\t\t\t// Split message buffer into statements.\n\t\t\tconst statementParts = this.messageBuffer.split(ElectrumProtocol.statementDelimiter);\n\n\t\t\t// For as long as we still have statements to parse..\n\t\t\twhile(statementParts.length > 1)\n\t\t\t{\n\t\t\t\t// Move the first statement to its own variable.\n\t\t\t\tconst currentStatementList = String(statementParts.shift());\n\n\t\t\t\t// Parse the statement into an object or list of objects.\n\t\t\t\tlet statementList = parse(currentStatementList, null, this.options.useBigInt ? parseNumberAndBigInt : parseFloat) as RPCResponse | RPCResponse[];\n\n\t\t\t\t// Wrap the statement in an array if it is not already a batched statement list.\n\t\t\t\tif(!Array.isArray(statementList))\n\t\t\t\t{\n\t\t\t\t\tstatementList = [ statementList ];\n\t\t\t\t}\n\n\t\t\t\t// For as long as there is statements in the result set..\n\t\t\t\twhile(statementList.length > 0)\n\t\t\t\t{\n\t\t\t\t\t// Move the first statement from the batch to its own variable.\n\t\t\t\t\tconst currentStatement = statementList.shift();\n\n\t\t\t\t\t// If the current statement is a subscription notification..\n\t\t\t\t\tif(isRPCNotification(currentStatement))\n\t\t\t\t\t{\n\t\t\t\t\t\t// Emit the notification for handling higher up in the stack.\n\t\t\t\t\t\tthis.emit('response', currentStatement);\n\n\t\t\t\t\t\t// Consider this statement handled.\n\t\t\t\t\t\tcontinue;\n\t\t\t\t\t}\n\n\t\t\t\t\t// If the current statement is a version negotiation response..\n\t\t\t\t\tif(currentStatement.id === 'versionNegotiation')\n\t\t\t\t\t{\n\t\t\t\t\t\tif(isRPCErrorResponse(currentStatement))\n\t\t\t\t\t\t{\n\t\t\t\t\t\t\t// Then emit a failed version negotiation response signal.\n\t\t\t\t\t\t\tthis.emit('version', { error: currentStatement.error });\n\t\t\t\t\t\t}\n\t\t\t\t\t\telse\n\t\t\t\t\t\t{\n\t\t\t\t\t\t\t// Extract the software and protocol version reported.\n\t\t\t\t\t\t\tconst [ software, protocol ] = currentStatement.result;\n\n\t\t\t\t\t\t\t// Emit a successful version negotiation response signal.\n\t\t\t\t\t\t\tthis.emit('version', { software, protocol });\n\t\t\t\t\t\t}\n\n\t\t\t\t\t\t// Consider this statement handled.\n\t\t\t\t\t\tcontinue;\n\t\t\t\t\t}\n\n\t\t\t\t\t// If the current statement is a keep-alive response..\n\t\t\t\t\tif(currentStatement.id === 'keepAlive')\n\t\t\t\t\t{\n\t\t\t\t\t\t// Do nothing and consider this statement handled.\n\t\t\t\t\t\tcontinue;\n\t\t\t\t\t}\n\n\t\t\t\t\t// Emit the statements for handling higher up in the stack.\n\t\t\t\t\tthis.emit('response', currentStatement);\n\t\t\t\t}\n\t\t\t}\n\n\t\t\t// Store the remaining statement as the current message buffer.\n\t\t\tthis.messageBuffer = statementParts.shift() || '';\n\t\t}\n\t}\n\n\t/**\n\t * Sends a keep-alive message to the host.\n\t *\n\t * @returns true if the ping message was fully flushed to the socket, false if\n\t * part of the message is queued in the user memory\n\t */\n\tping(): boolean\n\t{\n\t\t// Write a log message.\n\t\tdebug.ping(`Sending keep-alive ping to '${this.hostIdentifier}'`);\n\n\t\t// Craft a keep-alive message.\n\t\tconst message = ElectrumProtocol.buildRequestObject('server.ping', [], 'keepAlive');\n\n\t\t// Send the keep-alive message.\n\t\tconst status = this.send(message);\n\n\t\t// Return the ping status.\n\t\treturn status;\n\t}\n\n\t/**\n\t * Initiates the network connection negotiates a protocol version. Also emits the 'connect' signal if successful.\n\t *\n\t * @throws {Error} if the socket connection fails.\n\t * @returns a promise resolving when the connection is established\n\t */\n\tasync connect(): Promise<void>\n\t{\n\t\t// If we are already connected return true.\n\t\tif(this.status === ConnectionStatus.CONNECTED)\n\t\t{\n\t\t\treturn;\n\t\t}\n\n\t\t// Indicate that the connection is connecting\n\t\tthis.status = ConnectionStatus.CONNECTING;\n\n\t\t// Emit a connect event now that the connection is being set up.\n\t\tthis.emit('connecting');\n\n\t\t// Define a function to wrap connection as a promise.\n\t\tconst connectionResolver = (resolve: ResolveFunction<void>, reject: RejectFunction): void =>\n\t\t{\n\t\t\tconst rejector = (error: Error): void =>\n\t\t\t{\n\t\t\t\t// Set the status back to disconnected\n\t\t\t\tthis.status = ConnectionStatus.DISCONNECTED;\n\n\t\t\t\t// Emit a connect event indicating that we failed to connect.\n\t\t\t\tthis.emit('disconnected');\n\n\t\t\t\t// Reject with the error as reason\n\t\t\t\treject(error);\n\t\t\t};\n\n\t\t\t// Replace previous error handlers to reject the promise on failure.\n\t\t\tthis.socket.removeAllListeners('error');\n\t\t\tthis.socket.once('error', rejector);\n\n\t\t\t// Define a function to wrap version negotiation as a callback.\n\t\t\tconst versionNegotiator = (): void =>\n\t\t\t{\n\t\t\t\t// Write a log message to show that we have started version negotiation.\n\t\t\t\tdebug.network(`Requesting protocol version ${this.version} with '${this.hostIdentifier}'.`);\n\n\t\t\t\t// remove the one-time error handler since no error was detected.\n\t\t\t\tthis.socket.removeListener('error', rejector);\n\n\t\t\t\t// Build a version negotiation message.\n\t\t\t\tconst versionMessage = ElectrumProtocol.buildRequestObject('server.version', [ this.application, this.version ], 'versionNegotiation');\n\n\t\t\t\t// Define a function to wrap version validation as a function.\n\t\t\t\tconst versionValidator = (version: VersionNegotiationResponse): void =>\n\t\t\t\t{\n\t\t\t\t\t// Check if version negotiation failed.\n\t\t\t\t\tif(isVersionRejected(version))\n\t\t\t\t\t{\n\t\t\t\t\t\t// Disconnect from the host.\n\t\t\t\t\t\tthis.disconnect(true);\n\n\t\t\t\t\t\t// Declare an error message.\n\t\t\t\t\t\tconst errorMessage = 'unsupported protocol version.';\n\n\t\t\t\t\t\t// Log the error.\n\t\t\t\t\t\tdebug.errors(`Failed to connect with ${this.hostIdentifier} due to ${errorMessage}`);\n\n\t\t\t\t\t\t// Reject the connection with false since version negotiation failed.\n\t\t\t\t\t\treject(errorMessage);\n\t\t\t\t\t}\n\t\t\t\t\t// Check if the host supports our requested protocol version.\n\t\t\t\t\t// NOTE: the server responds with version numbers that truncate 0's, so 1.5.0 turns into 1.5.\n\t\t\t\t\telse if((version.protocol !== this.version) && (`${version.protocol}.0` !== this.version) && (`${version.protocol}.0.0` !== this.version))\n\t\t\t\t\t{\n\t\t\t\t\t\t// Disconnect from the host.\n\t\t\t\t\t\tthis.disconnect(true);\n\n\t\t\t\t\t\t// Declare an error message.\n\t\t\t\t\t\tconst errorMessage = `incompatible protocol version negotiated (${version.protocol} !== ${this.version}).`;\n\n\t\t\t\t\t\t// Log the error.\n\t\t\t\t\t\tdebug.errors(`Failed to connect with ${this.hostIdentifier} due to ${errorMessage}`);\n\n\t\t\t\t\t\t// Reject the connection with false since version negotiation failed.\n\t\t\t\t\t\treject(errorMessage);\n\t\t\t\t\t}\n\t\t\t\t\telse\n\t\t\t\t\t{\n\t\t\t\t\t\t// Write a log message.\n\t\t\t\t\t\tdebug.network(`Negotiated protocol version ${version.protocol} with '${this.hostIdentifier}', powered by ${version.software}.`);\n\n\t\t\t\t\t\t// Set connection status to connected\n\t\t\t\t\t\tthis.status = ConnectionStatus.CONNECTED;\n\n\t\t\t\t\t\t// Emit a connect event now that the connection is usable.\n\t\t\t\t\t\tthis.emit('connected');\n\n\t\t\t\t\t\t// Resolve the connection promise since we successfully connected and negotiated protocol version.\n\t\t\t\t\t\tresolve();\n\t\t\t\t\t}\n\t\t\t\t};\n\n\t\t\t\t// Listen for version negotiation once.\n\t\t\t\tthis.once('version', versionValidator);\n\n\t\t\t\t// Send the version negotiation message.\n\t\t\t\tthis.send(versionMessage);\n\t\t\t};\n\n\t\t\t// Prepare the version negotiation.\n\t\t\tthis.socket.once('connected', versionNegotiator);\n\n\t\t\t// Set up handler for network errors.\n\t\t\tthis.socket.on('error', this.onSocketError.bind(this));\n\n\t\t\t// Connect to the server.\n\t\t\tthis.socket.connect();\n\t\t};\n\n\t\t// Wait until connection is established and version negotiation succeeds.\n\t\tawait new Promise<void>(connectionResolver);\n\t}\n\n\t/**\n\t * Restores the network connection.\n\t */\n\tasync reconnect(): Promise<void>\n\t{\n\t\t// If a reconnect timer is set, remove it\n\t\tawait this.clearReconnectTimer();\n\n\t\t// Write a log message.\n\t\tdebug.network(`Trying to reconnect to '${this.hostIdentifier}'..`);\n\n\t\t// Set the status to reconnecting for more accurate log messages.\n\t\tthis.status = ConnectionStatus.RECONNECTING;\n\n\t\t// Emit a connect event now that the connection is usable.\n\t\tthis.emit('reconnecting');\n\n\t\t// Disconnect the underlying socket.\n\t\tthis.socket.disconnect();\n\n\t\ttry\n\t\t{\n\t\t\t// Try to connect again.\n\t\t\tawait this.connect();\n\t\t}\n\t\tcatch (_error)\n\t\t{\n\t\t\t// Do nothing as the error should be handled via the disconnect and error signals.\n\t\t}\n\t}\n\n\t/**\n\t * Removes the current reconnect timer.\n\t */\n\tclearReconnectTimer(): void\n\t{\n\t\t// If a reconnect timer is set, remove it\n\t\tif(this.reconnectTimer)\n\t\t{\n\t\t\tclearTimeout(this.reconnectTimer);\n\t\t}\n\n\t\t// Reset the timer reference.\n\t\tthis.reconnectTimer = undefined;\n\t}\n\n\t/**\n\t * Removes the current keep-alive timer.\n\t */\n\tclearKeepAliveTimer(): void\n\t{\n\t\t// If a keep-alive timer is set, remove it\n\t\tif(this.keepAliveTimer)\n\t\t{\n\t\t\tclearTimeout(this.keepAliveTimer);\n\t\t}\n\n\t\t// Reset the timer reference.\n\t\tthis.keepAliveTimer = undefined;\n\t}\n\n\t/**\n\t * Initializes the keep alive timer loop.\n\t */\n\tsetupKeepAliveTimer(): void\n\t{\n\t\t// If the keep-alive timer loop is not currently set up..\n\t\tif(!this.keepAliveTimer)\n\t\t{\n\t\t\t// Set a new keep-alive timer.\n\t\t\tthis.keepAliveTimer = setTimeout(this.ping.bind(this), this.options.sendKeepAliveIntervalInMilliSeconds) as unknown as number;\n\t\t}\n\t}\n\n\t/**\n\t * Tears down the current connection and removes all event listeners on disconnect.\n\t *\n\t * @param force       - disconnect even if the connection has not been fully established yet.\n\t * @param intentional - update connection state if disconnect is intentional.\n\t *\n\t * @returns true if successfully disconnected, or false if there was no connection.\n\t */\n\tasync disconnect(force: boolean = false, intentional: boolean = true): Promise<boolean>\n\t{\n\t\t// Return early when there is nothing to disconnect from\n\t\tif(this.status === ConnectionStatus.DISCONNECTED && !force)\n\t\t{\n\t\t\t// Return false to indicate that there was nothing to disconnect from.\n\t\t\treturn false;\n\t\t}\n\n\t\t// Update connection state if the disconnection is intentional.\n\t\t// NOTE: The state is meant to represent what the client is requesting, but\n\t\t//       is used internally to handle visibility changes in browsers to ensure functional reconnection.\n\t\tif(intentional)\n\t\t{\n\t\t\t// Set connection status to null to indicate tear-down is currently happening.\n\t\t\tthis.status = ConnectionStatus.DISCONNECTING;\n\t\t}\n\n\t\t// Emit a connect event to indicate that we are disconnecting.\n\t\tthis.emit('disconnecting');\n\n\t\t// If a keep-alive timer is set, remove it.\n\t\tawait this.clearKeepAliveTimer();\n\n\t\t// If a reconnect timer is set, remove it\n\t\tawait this.clearReconnectTimer();\n\n\t\tconst disconnectResolver = (resolve: ResolveFunction<boolean>): void =>\n\t\t{\n\t\t\t// Resolve to true after the connection emits a disconnect\n\t\t\tthis.once('disconnected', () => resolve(true));\n\n\t\t\t// Close the connection on the socket level.\n\t\t\tthis.socket.disconnect();\n\t\t};\n\n\t\t// Return true to indicate that we disconnected.\n\t\treturn new Promise<boolean>(disconnectResolver);\n\t}\n\n\t/**\n\t * Updates the connection state based on browser reported connectivity.\n\t *\n\t * Most modern browsers are able to provide information on the connection state\n\t * which allows for significantly faster response times to network changes compared\n\t * to waiting for network requests to fail.\n\t *\n\t * When available, we make use of this to fail early to provide a better user experience.\n\t */\n\tasync handleNetworkChange(): Promise<void>\n\t{\n\t\t// Do nothing if we do not have the navigator available.\n\t\tif(typeof window.navigator === 'undefined')\n\t\t{\n\t\t\treturn;\n\t\t}\n\n\t\t// Attempt to reconnect to the network now that we may be online again.\n\t\tif(window.navigator.onLine === true)\n\t\t{\n\t\t\tthis.reconnect();\n\t\t}\n\n\t\t// Disconnected from the network so that cleanup can happen while we're offline.\n\t\tif(window.navigator.onLine !== true)\n\t\t{\n\t\t\tconst forceDisconnect = true;\n\t\t\tconst isIntentional = true;\n\n\t\t\tthis.disconnect(forceDisconnect, isIntentional);\n\t\t}\n\t}\n\n\t/**\n\t * Updates connection state based on application visibility.\n\t *\n\t * Some browsers will disconnect network connections when the browser is out of focus,\n\t * which would normally cause our reconnect-on-timeout routines to trigger, but that\n\t * results in a poor user experience since the events are not handled consistently\n\t * and sometimes it can take some time after restoring focus to the browser.\n\t *\n\t * By manually disconnecting when this happens we prevent the default reconnection routines\n\t * and make the behavior consistent across browsers.\n\t */\n\tasync handleVisibilityChange(): Promise<void>\n\t{\n\t\t// Disconnect when application is removed from focus.\n\t\tif(document.visibilityState === 'hidden')\n\t\t{\n\t\t\tconst forceDisconnect = true;\n\t\t\tconst isIntentional = true;\n\n\t\t\tthis.disconnect(forceDisconnect, isIntentional);\n\t\t}\n\n\t\t// Reconnect when application is returned to focus.\n\t\tif(document.visibilityState === 'visible')\n\t\t{\n\t\t\tthis.reconnect();\n\t\t}\n\t}\n\n\t/**\n\t * Sends an arbitrary message to the server.\n\t *\n\t * @param message - json encoded request object to send to the server, as a string.\n\t *\n\t * @returns true if the message was fully flushed to the socket, false if part of the message\n\t * is queued in the user memory\n\t */\n\tsend(message: string): boolean\n\t{\n\t\t// Remove the current keep-alive timer if it exists.\n\t\tthis.clearKeepAliveTimer();\n\n\t\t// Get the current timestamp in milliseconds.\n\t\tconst currentTime = Date.now();\n\n\t\t// Follow up and verify that the message got sent..\n\t\tconst verificationTimer = setTimeout(this.verifySend.bind(this, currentTime), this.socket.timeout) as unknown as number;\n\n\t\t// Store the verification timer locally so that it can be cleared when data has been received.\n\t\tthis.verifications.push(verificationTimer);\n\n\t\t// Set a new keep-alive timer.\n\t\tthis.setupKeepAliveTimer();\n\n\t\t// Write the message to the network socket.\n\t\treturn this.socket.write(message + ElectrumProtocol.statementDelimiter);\n\t}\n\n\t// --- Event managers. --- //\n\n\t/**\n\t * Marks the connection as timed out and schedules reconnection if we have not\n\t * received data within the expected time frame.\n\t */\n\tverifySend(sentTimestamp: number): void\n\t{\n\t\t// If we haven't received any data since we last sent data out..\n\t\tif(Number(this.lastReceivedTimestamp) < sentTimestamp)\n\t\t{\n\t\t\t// If this connection is already disconnected, we do not change anything\n\t\t\tif((this.status === ConnectionStatus.DISCONNECTED) || (this.status === ConnectionStatus.DISCONNECTING))\n\t\t\t{\n\t\t\t\t// debug.warning(`Tried to verify already disconnected connection to '${this.hostIdentifier}'`);\n\n\t\t\t\treturn;\n\t\t\t}\n\n\t\t\t// Remove the current keep-alive timer if it exists.\n\t\t\tthis.clearKeepAliveTimer();\n\n\t\t\t// Write a notification to the logs.\n\t\t\tdebug.network(`Connection to '${this.hostIdentifier}' timed out.`);\n\n\t\t\t// Close the connection to avoid re-use.\n\t\t\t// NOTE: This initiates reconnection routines if the connection has not\n\t\t\t//       been marked as intentionally disconnected.\n\t\t\tthis.socket.disconnect();\n\t\t}\n\t}\n\n\t/**\n\t * Updates the connection status when a connection is confirmed.\n\t */\n\tonSocketConnect(): void\n\t{\n\t\t// If a reconnect timer is set, remove it.\n\t\tthis.clearReconnectTimer();\n\n\t\t// Set up the initial timestamp for when we last received data from the server.\n\t\tthis.lastReceivedTimestamp = Date.now();\n\n\t\t// Set up the initial keep-alive timer.\n\t\tthis.setupKeepAliveTimer();\n\n\t\t// Clear all temporary error listeners.\n\t\tthis.socket.removeAllListeners('error');\n\n\t\t// Set up handler for network errors.\n\t\tthis.socket.on('error', this.onSocketError.bind(this));\n\t}\n\n\t/**\n\t * Updates the connection status when a connection is ended.\n\t */\n\tonSocketDisconnect(): void\n\t{\n\t\t// Remove the current keep-alive timer if it exists.\n\t\tthis.clearKeepAliveTimer();\n\n\t\t// If this is a connection we're trying to tear down..\n\t\tif(this.status === ConnectionStatus.DISCONNECTING)\n\t\t{\n\t\t\t// Mark the connection as disconnected.\n\t\t\tthis.status = ConnectionStatus.DISCONNECTED;\n\n\t\t\t// Send a disconnect signal higher up the stack.\n\t\t\tthis.emit('disconnected');\n\n\t\t\t// If a reconnect timer is set, remove it.\n\t\t\tthis.clearReconnectTimer();\n\n\t\t\t// Remove all event listeners\n\t\t\tthis.removeAllListeners();\n\n\t\t\t// Write a log message.\n\t\t\tdebug.network(`Disconnected from '${this.hostIdentifier}'.`);\n\t\t}\n\t\telse\n\t\t{\n\t\t\t// If this is for an established connection..\n\t\t\tif(this.status === ConnectionStatus.CONNECTED)\n\t\t\t{\n\t\t\t\t// Write a notification to the logs.\n\t\t\t\tdebug.errors(`Connection with '${this.hostIdentifier}' was closed, trying to reconnect in ${this.options.reconnectAfterMilliSeconds / 1000} seconds.`);\n\t\t\t}\n\t\t\t// If this is a connection that is currently connecting, reconnecting or already disconnected..\n\t\t\telse\n\t\t\t{\n\t\t\t\t// Do nothing\n\n\t\t\t\t// NOTE: This error message is useful during manual debugging of reconnections.\n\t\t\t\t// debug.errors(`Lost connection with reconnecting or already disconnected server '${this.hostIdentifier}'.`);\n\t\t\t}\n\n\t\t\t// Mark the connection as disconnected for now..\n\t\t\tthis.status = ConnectionStatus.DISCONNECTED;\n\n\t\t\t// Send a disconnect signal higher up the stack.\n\t\t\tthis.emit('disconnected');\n\n\t\t\t// If we don't have a pending reconnection timer..\n\t\t\tif(!this.reconnectTimer)\n\t\t\t{\n\t\t\t\t// Attempt to reconnect after one keep-alive duration.\n\t\t\t\tthis.reconnectTimer = setTimeout(this.reconnect.bind(this), this.options.reconnectAfterMilliSeconds) as unknown as number;\n\t\t\t}\n\t\t}\n\t}\n\n\t/**\n\t * Notify administrator of any unexpected errors.\n\t */\n\tonSocketError(error: unknown | undefined): void\n\t{\n\t\t// Report a generic error if no error information is present.\n\t\t// NOTE: When using WSS, the error event explicitly\n\t\t//       only allows to send a \"simple\" event without data.\n\t\t//       https://stackoverflow.com/a/18804298\n\t\tif(typeof error === 'undefined')\n\t\t{\n\t\t\t// Do nothing, and instead rely on the socket disconnect event for further information.\n\t\t\treturn;\n\t\t}\n\n\t\t// Log the error, as there is nothing we can do to actually handle it.\n\t\tdebug.errors(`Network error ('${this.hostIdentifier}'): `, error);\n\t}\n}\n","import type { ElectrumNetworkOptions } from './interfaces.ts';\n\n// Define number of milliseconds per second for legibility.\nconst MILLI_SECONDS_PER_SECOND = 1000;\n\n/**\n * Configure default options.\n */\nexport const defaultNetworkOptions: ElectrumNetworkOptions =\n{\n\t// By default, all numbers including integers are parsed as regular JavaScript numbers.\n\tuseBigInt: false,\n\n\t// Send a ping message every seconds, to detect network problem as early as possible.\n\tsendKeepAliveIntervalInMilliSeconds: 1 * MILLI_SECONDS_PER_SECOND,\n\n\t// Try to reconnect 5 seconds after unintentional disconnects.\n\treconnectAfterMilliSeconds: 5 * MILLI_SECONDS_PER_SECOND,\n\n\t// Try to detect stale connections 5 seconds after every send.\n\tverifyConnectionTimeoutInMilliSeconds: 5 * MILLI_SECONDS_PER_SECOND,\n\n\t// Automatically manage the connection for a consistent behavior across browsers and devices.\n\tdisableBrowserVisibilityHandling: false,\n\tdisableBrowserConnectivityHandling: false,\n};\n","import debug from '@electrum-cash/debug-logs';\nimport { ElectrumConnection } from './electrum-connection.ts';\nimport { ElectrumProtocol } from './electrum-protocol.ts';\nimport { defaultNetworkOptions } from './constants.ts';\nimport { ConnectionStatus } from './enums.ts';\nimport { EventEmitter } from 'eventemitter3';\nimport { Mutex } from 'async-mutex';\nimport { isRPCNotification, isRPCErrorResponse } from './rpc-interfaces.ts';\nimport type { RPCParameter, RPCNotification, RPCResponse } from './rpc-interfaces.ts';\nimport type { ElectrumNetworkOptions, ElectrumClientEvents, ElectrumSocket, ResolveFunction, RequestResolver, RequestResponse } from './interfaces.ts';\n\n/**\n * High-level Electrum client that lets applications send requests and subscribe to notification events from a server.\n */\nclass ElectrumClient<ElectrumEvents extends ElectrumClientEvents> extends EventEmitter<ElectrumClientEvents | ElectrumEvents> implements ElectrumClientEvents\n{\n\t/**\n\t * The name and version of the server software indexing the blockchain.\n\t */\n\tpublic software: string;\n\n\t/**\n\t * The genesis hash of the blockchain indexed by the server.\n\t * @remarks This is only available after a 'server.features' call.\n\t */\n\tpublic genesisHash: string;\n\n\t/**\n\t * The chain height of the blockchain indexed by the server.\n\t * @remarks This is only available after a 'blockchain.headers.subscribe' call.\n\t */\n\tpublic chainHeight: number;\n\n\t/**\n\t * Timestamp of when we last received data from the server indexing the blockchain.\n\t */\n\tpublic lastReceivedTimestamp: number;\n\n\t/**\n\t * Number corresponding to the underlying connection status.\n\t */\n\tpublic get status(): ConnectionStatus\n\t{\n\t\treturn this.connection.status;\n\t}\n\n\t// Declare instance variables\n\tprivate connection: ElectrumConnection;\n\n\t// Initialize an empty list of subscription metadata.\n\tprivate subscriptionMethods: Record<string, Set<string>> = {};\n\n\t// Start counting the request IDs from 0\n\tprivate requestId = 0;\n\n\t// Initialize an empty dictionary for keeping track of request resolvers\n\tprivate requestResolvers: { [index: number]: RequestResolver } = {};\n\n\t// Mutex lock used to prevent simultaneous connect() and disconnect() calls.\n\tprivate connectionLock = new Mutex();\n\n\t/**\n\t * Initializes an Electrum client.\n\t *\n\t * @param application       - your application name, used to identify to the electrum host.\n\t * @param version           - protocol version to use with the host.\n\t * @param socketOrHostname  - pre-configured electrum socket or fully qualified domain name or IP number of the host\n\t * @param options           - ...\n\t *\n\t * @throws {Error} if `version` is not a valid version string.\n\t */\n\tconstructor(\n\t\tpublic application: string,\n\t\tpublic version: string,\n\t\tpublic socketOrHostname: ElectrumSocket | string,\n\t\tpublic options: ElectrumNetworkOptions = {},\n\t)\n\t{\n\t\t// Initialize the event emitter.\n\t\tsuper();\n\n\t\t// Update default options with the provided values.\n\t\tconst networkOptions: ElectrumNetworkOptions = { ...defaultNetworkOptions, ...options };\n\n\t\t// Set up a connection to an electrum server.\n\t\tthis.connection = new ElectrumConnection(application, version, socketOrHostname, networkOptions);\n\t}\n\n\t// Expose hostIdentifier from the connection.\n\tget hostIdentifier(): string\n\t{\n\t\treturn this.connection.hostIdentifier;\n\t}\n\n\t// Expose port from the connection.\n\tget encrypted(): boolean\n\t{\n\t\treturn this.connection.encrypted;\n\t}\n\n\t/**\n\t * Connects to the remote server.\n\t *\n\t * @throws {Error} if the socket connection fails.\n\t * @returns a promise resolving when the connection is established.\n\t */\n\tasync connect(): Promise<void>\n\t{\n\t\t// Create a lock so that multiple connects/disconnects cannot race each other.\n\t\tconst unlock = await this.connectionLock.acquire();\n\n\t\ttry\n\t\t{\n\t\t\t// If we are already connected, do not attempt to connect again.\n\t\t\tif(this.connection.status === ConnectionStatus.CONNECTED)\n\t\t\t{\n\t\t\t\treturn;\n\t\t\t}\n\n\t\t\t// Listen for parsed statements.\n\t\t\tthis.connection.on('response', this.response.bind(this));\n\n\t\t\t// Hook up handles for the connected and disconnected events.\n\t\t\tthis.connection.on('connected', this.resubscribeOnConnect.bind(this));\n\t\t\tthis.connection.on('disconnected', this.onConnectionDisconnect.bind(this));\n\n\t\t\t// Relay connecting and reconnecting events.\n\t\t\tthis.connection.on('connecting', this.handleConnectionStatusChanges.bind(this, 'connecting'));\n\t\t\tthis.connection.on('disconnecting', this.handleConnectionStatusChanges.bind(this, 'disconnecting'));\n\t\t\tthis.connection.on('reconnecting', this.handleConnectionStatusChanges.bind(this, 'reconnecting'));\n\n\t\t\t// Hook up client metadata gathering functions.\n\t\t\tthis.connection.on('version', this.storeSoftwareVersion.bind(this));\n\t\t\tthis.connection.on('received', this.updateLastReceivedTimestamp.bind(this));\n\n\t\t\t// Relay error events.\n\t\t\tthis.connection.on('error', this.emit.bind(this, 'error'));\n\n\t\t\t// Connect with the server.\n\t\t\tawait this.connection.connect();\n\t\t}\n\t\t// Always release our lock so that we do not end up in a stuck-state.\n\t\tfinally\n\t\t{\n\t\t\tunlock();\n\t\t}\n\t}\n\n\t/**\n\t * Disconnects from the remote server and removes all event listeners/subscriptions and open requests.\n\t *\n\t * @param force               - disconnect even if the connection has not been fully established yet.\n\t * @param retainSubscriptions - retain subscription data so they will be restored on reconnection.\n\t *\n\t * @returns true if successfully disconnected, or false if there was no connection.\n\t */\n\tasync disconnect(force: boolean = false, retainSubscriptions: boolean = false): Promise<boolean>\n\t{\n\t\tif(!retainSubscriptions)\n\t\t{\n\t\t\t// Cancel all event listeners.\n\t\t\tthis.removeAllListeners();\n\n\t\t\t// Remove all subscription data\n\t\t\tthis.subscriptionMethods = {};\n\t\t}\n\n\t\t// Disconnect from the remote server.\n\t\treturn this.connection.disconnect(force);\n\t}\n\n\t/**\n\t * Calls a method on the remote server with the supplied parameters.\n\t *\n\t * @param method     - name of the method to call.\n\t * @param parameters - one or more parameters for the method.\n\t *\n\t * @throws {Error} if the client is disconnected.\n\t * @returns a promise that resolves with the result of the method or an Error.\n\t */\n\tasync request(method: string, ...parameters: RPCParameter[]): Promise<Error | RequestResponse>\n\t{\n\t\t// If we are not connected to a server..\n\t\tif(this.connection.status !== ConnectionStatus.CONNECTED)\n\t\t{\n\t\t\t// Reject the request with a disconnected error message.\n\t\t\tthrow(new Error(`Unable to send request to a disconnected server '${this.hostIdentifier}'.`));\n\t\t}\n\n\t\t// Increase the request ID by one.\n\t\tthis.requestId += 1;\n\n\t\t// Store a copy of the request id.\n\t\tconst id = this.requestId;\n\n\t\t// Format the arguments as an electrum request object.\n\t\tconst message = ElectrumProtocol.buildRequestObject(method, parameters, id);\n\n\t\t// Define a function to wrap the request in a promise.\n\t\tconst requestResolver = (resolve: ResolveFunction<Error | RequestResponse>): void =>\n\t\t{\n\t\t\t// Add a request resolver for this promise to the list of requests.\n\t\t\tthis.requestResolvers[id] = (error?: Error, data?: RequestResponse) =>\n\t\t\t{\n\t\t\t\t// If the resolution failed..\n\t\t\t\tif(error)\n\t\t\t\t{\n\t\t\t\t\t// Resolve the promise with the error for the application to handle.\n\t\t\t\t\tresolve(error);\n\t\t\t\t}\n\t\t\t\telse\n\t\t\t\t{\n\t\t\t\t\t// Resolve the promise with the request results.\n\t\t\t\t\tresolve(data);\n\t\t\t\t}\n\t\t\t};\n\n\t\t\t// Send the request message to the remote server.\n\t\t\tthis.connection.send(message);\n\t\t};\n\n\t\t// Write a log message.\n\t\tdebug.network(`Sending request '${method}' to '${this.hostIdentifier}'`);\n\n\t\t// return a promise to deliver results later.\n\t\treturn new Promise<Error | RequestResponse>(requestResolver);\n\t}\n\n\t/**\n\t * Subscribes to the method and payload at the server.\n\t *\n\t * @remarks the response for the subscription request is issued as a notification event.\n\t *\n\t * @param method     - one of the subscribable methods the server supports.\n\t * @param parameters - one or more parameters for the method.\n\t *\n\t * @throws {Error} if the client is disconnected.\n\t * @returns a promise resolving when the subscription is established.\n\t */\n\tasync subscribe(method: string, ...parameters: RPCParameter[]): Promise<void>\n\t{\n\t\t// Initialize an empty list of subscription payloads, if needed.\n\t\tif(!this.subscriptionMethods[method])\n\t\t{\n\t\t\tthis.subscriptionMethods[method] = new Set<string>();\n\t\t}\n\n\t\t// Store the subscription parameters to track what data we have subscribed to.\n\t\tthis.subscriptionMethods[method].add(JSON.stringify(parameters));\n\n\t\t// Send initial subscription request.\n\t\tconst requestData = await this.request(method, ...parameters);\n\n\t\t// If the request failed, throw it as an error.\n\t\tif(requestData instanceof Error)\n\t\t{\n\t\t\tthrow(requestData);\n\t\t}\n\n\t\t// If the request returned more than one data point..\n\t\tif(Array.isArray(requestData))\n\t\t{\n\t\t\t// .. throw an error, as this breaks our expectation for subscriptions.\n\t\t\tthrow(new Error('Subscription request returned an more than one data point.'));\n\t\t}\n\n\t\t// Construct a notification structure to package the initial result as a notification.\n\t\tconst notification: RPCNotification =\n\t\t{\n\t\t\tjsonrpc: '2.0',\n\t\t\tmethod: method,\n\t\t\tparams: [ ...parameters, requestData ],\n\t\t};\n\n\t\t// Manually emit an event for the initial response.\n\t\tthis.emit('notification', notification);\n\n\t\t// Try to update the chain height.\n\t\tthis.updateChainHeightFromHeadersNotifications(notification);\n\t}\n\n\t/**\n\t * Unsubscribes to the method at the server and removes any callback functions\n\t * when there are no more subscriptions for the method.\n\t *\n\t * @param method     - a previously subscribed to method.\n\t * @param parameters - one or more parameters for the method.\n\t *\n\t * @throws {Error} if no subscriptions exist for the combination of the provided `method` and `parameters.\n\t * @throws {Error} if the client is disconnected.\n\t * @returns a promise resolving when the subscription is removed.\n\t */\n\tasync unsubscribe(method: string, ...parameters: RPCParameter[]): Promise<void>\n\t{\n\t\t// Throw an error if the client is disconnected.\n\t\tif(this.connection.status !== ConnectionStatus.CONNECTED)\n\t\t{\n\t\t\tthrow(new Error(`Unable to send unsubscribe request to a disconnected server '${this.hostIdentifier}'.`));\n\t\t}\n\n\t\t// If this method has no subscriptions..\n\t\tif(!this.subscriptionMethods[method])\n\t\t{\n\t\t\t// Reject this promise with an explanation.\n\t\t\tthrow(new Error(`Cannot unsubscribe from '${method}' since the method has no subscriptions.`));\n\t\t}\n\n\t\t// Pack up the parameters as a long string.\n\t\tconst subscriptionParameters = JSON.stringify(parameters);\n\n\t\t// If the method payload could not be located..\n\t\tif(!this.subscriptionMethods[method].has(subscriptionParameters))\n\t\t{\n\t\t\t// Reject this promise with an explanation.\n\t\t\tthrow(new Error(`Cannot unsubscribe from '${method}' since it has no subscription with the given parameters.`));\n\t\t}\n\n\t\t// Remove this specific subscription payload from internal tracking.\n\t\tthis.subscriptionMethods[method].delete(subscriptionParameters);\n\n\t\t// Send unsubscription request to the server\n\t\t// NOTE: As a convenience we allow users to define the method as the subscribe or unsubscribe version.\n\t\tawait this.request(method.replace('.subscribe', '.unsubscribe'), ...parameters);\n\n\t\t// Write a log message.\n\t\tdebug.client(`Unsubscribed from '${String(method)}' for the '${subscriptionParameters}' parameters.`);\n\t}\n\n\t/**\n\t * Restores existing subscriptions without updating status or triggering manual callbacks.\n\t *\n\t * @throws {Error} if subscription data cannot be found for all stored event names.\n\t * @throws {Error} if the client is disconnected.\n\t * @returns a promise resolving to true when the subscriptions are restored.\n\t *\n\t * @ignore\n\t */\n\tprivate async resubscribeOnConnect(): Promise<void>\n\t{\n\t\t// Write a log message.\n\t\tdebug.client(`Connected to '${this.hostIdentifier}'.`);\n\n\t\t// Synchronize with the underlying connection status.\n\t\tthis.handleConnectionStatusChanges('connected');\n\n\t\t// Initialize an empty list of resubscription promises.\n\t\tconst resubscriptionPromises = [];\n\n\t\t// For each method we have a subscription for..\n\t\tfor(const method in this.subscriptionMethods)\n\t\t{\n\t\t\t// .. and for each parameter we have previously been subscribed to..\n\t\t\tfor(const parameterJSON of this.subscriptionMethods[method].values())\n\t\t\t{\n\t\t\t\t// restore the parameters from JSON.\n\t\t\t\tconst parameters = JSON.parse(parameterJSON);\n\n\t\t\t\t// Send a subscription request.\n\t\t\t\tresubscriptionPromises.push(this.subscribe(method, ...parameters));\n\t\t\t}\n\n\t\t\t// Wait for all re-subscriptions to complete.\n\t\t\tawait Promise.all(resubscriptionPromises);\n\t\t}\n\n\t\t// Write a log message if there was any subscriptions to restore.\n\t\tif(resubscriptionPromises.length > 0)\n\t\t{\n\