@mr-zwets/bchn-api-wrapper 1.0.1 → 1.0.2

package/src/interfaces/rpcInterfaces/zmq.ts

@@ -1,11 +1,12 @@
-/* --- Zmq Commands --- */
-// progress 1/1
-
-export interface GetZmqNotifications {
-  method: 'getzmqnotifications';
-  params: [];
-  response: {
-    type: string;
-    address: string;
-  }[]
-}
+/* --- Zmq Commands --- */
+// progress 1/1
+
+/** Returns active ZMQ notification endpoints. */
+export interface GetZmqNotifications {
+  method: 'getzmqnotifications';
+  params: [];
+  response: {
+    type: string;
+    address: string;
+  }[]
+}

package/src/restClient.ts

@@ -1,119 +1,134 @@
-import type { RestClientConfig, formatOptions, ResponseType } from "./interfaces/interfaces.js";
-import type {
-  BlockInfoNoTxDetails,
-  BlockInfoTxDetails,
-  ChainInfo,
-  HeaderInfo,
-  MempoolContent,
-  MempoolInfo,
-  TxDetails,
-  UtxosInfo
-} from "./interfaces/restInterfaces/interfaces.js";
-import { validateUrl } from "./utils/utils.js";
-
-export class BchnRestClient {
-  private baseUrl: string;
-  private timeoutMs: number;
-  private logger: Console;
-
-  constructor(config: RestClientConfig) {
-    this.baseUrl = validateUrl(config.url);
-    this.timeoutMs = config.timeoutMs ?? 5000;
-    this.logger = config.logger ?? console;
-  }
-
-  private async fetchFromNode<T, TFormat extends formatOptions>(
-    endpoint: string,
-    format: TFormat
-  ): Promise<ResponseType<TFormat, T>> {
-    try {
-      const response = await fetch(`${this.baseUrl}/rest/${endpoint}`, {
-        signal: AbortSignal.timeout(this.timeoutMs),
-      });
-      
-      if (!response.ok) {
-        throw new Error(`Error fetching data from ${endpoint}: ${response.statusText}`);
-      }
-      
-      if (format === 'json') {
-        return await response.json() as ResponseType<TFormat, T>;
-      } else {
-        return await response.text() as ResponseType<TFormat, T>;  // For 'bin' and 'hex', return raw text
-      }
-    } catch(error) {
-      let errorMessage: string | undefined
-      
-      // Check if the error is due to timeout or other fetch-related issues
-      if (typeof error === 'string') {
-        errorMessage = error;
-        this.logger.error(error);
-      } else if (error instanceof DOMException && error.name === 'TimeoutError') {
-        // If error is an instance DOMException TimeoutError
-        errorMessage = 'Request timed out';
-        this.logger.error(`Request to ${endpoint} timed out after ${this.timeoutMs} ms`);
-      } else {
-        this.logger.error(`Unknown error occurred during request to ${endpoint}`);
-        throw new Error(`Unknown error: ${error}`);
-      }
-      
-      // Always rethrow the error after logging
-      throw new Error(errorMessage);
-    }
-  }
-
-  // Get transaction details by transaction hash
-  async getTransaction<TFormat extends formatOptions = 'json'>(
-    txid: string, format:TFormat = 'json' as TFormat
-  ) {
-    return this.fetchFromNode<TxDetails, TFormat>(`tx/${txid}.${format}`, format);
-  }
-
-  // getBlock overload signatures 
-  // This is needed so the getBlock return type can depend on the 'includeTxDetails' boolean flag
-  async getBlock<TFormat extends formatOptions = 'json'>(
-    blockhash: string, includeTxDetails: true, format?:TFormat
-  ): Promise<TFormat extends 'json' ? BlockInfoTxDetails : string>;
-
-  async getBlock<TFormat extends formatOptions = 'json'>(
-    blockhash: string, includeTxDetails: false, format?:TFormat
-  ): Promise<TFormat extends 'json' ? BlockInfoNoTxDetails : string>;
-
-  // getBlock Implementation
-  async getBlock<TFormat extends formatOptions = 'json'>(
-    blockhash: string, includeTxDetails: boolean, format:TFormat = 'json' as TFormat
-  ): Promise<any> {
-    const path = includeTxDetails ? 'block' : 'block/notxdetails';
-    return this.fetchFromNode(`${path}/${blockhash}.${format}`, format);
-  }
-
-  // Get block headers starting from a specific block hash
-  async getBlockHeaders<TFormat extends formatOptions = 'json'>(
-    count: number, blockhash: string, format:TFormat = 'json' as TFormat
-  ) {
-    return this.fetchFromNode<HeaderInfo, TFormat>(`headers/${count}/${blockhash}.${format}`, format);
-  }
-
-  // Get chain info (chain state details)
-  async getChainInfo() {
-    return this.fetchFromNode<ChainInfo, 'json'>('chaininfo.json', 'json');
-  }
-
-  // Query UTXO set based on specific outpoints (txid and vout)
-  async getUTXOs<TFormat extends formatOptions = 'json'>(
-    checkmempool: boolean, outpoints: string[], format:TFormat = 'json' as TFormat
-  ) {
-    const path = (checkmempool ? 'checkmempool/' : '') + outpoints.join('/');
-    const endpoint = `getutxos/${path}.${format}`;
-    return this.fetchFromNode<UtxosInfo, TFormat>(endpoint, format);
-  }
-
-  // Get mempool information (basic)
-  async getMempoolInfo() {
-    return this.fetchFromNode<MempoolInfo, 'json'>('mempool/info.json', 'json');
-  }
-
-  // Get mempool contents (transactions currently in the mempool)
-  async getMempoolContents() {
-    return this.fetchFromNode<MempoolContent, 'json'>('mempool/contents.json', 'json');
-  }
-}
+import type { RestClientConfig, formatOptions, ResponseType } from "./interfaces/interfaces.js";
+import type {
+  BlockInfoNoTxDetails,
+  BlockInfoTxDetails,
+  BlockInfoWithPatterns,
+  ChainInfo,
+  HeaderInfo,
+  MempoolContent,
+  MempoolInfo,
+  TxDetails,
+  TxDetailsWithPatterns,
+  UtxosInfo
+} from "./interfaces/restInterfaces/interfaces.js";
+import { validateUrl } from "./utils/utils.js";
+
+/** REST client for read-only BCHN blockchain access via the REST interface. */
+export class BchnRestClient {
+  private baseUrl: string;
+  private timeoutMs: number;
+  private logger: Console;
+
+  constructor(config: RestClientConfig) {
+    this.baseUrl = validateUrl(config.url);
+    this.timeoutMs = config.timeoutMs ?? 5000;
+    this.logger = config.logger ?? console;
+  }
+
+  private async fetchFromNode<T, TFormat extends formatOptions>(
+    endpoint: string,
+    format: TFormat
+  ): Promise<ResponseType<TFormat, T>> {
+    try {
+      const response = await fetch(`${this.baseUrl}/rest/${endpoint}`, {
+        signal: AbortSignal.timeout(this.timeoutMs),
+      });
+
+      if (!response.ok) {
+        throw new Error(`Error fetching data from ${endpoint}: ${response.statusText}`);
+      }
+
+      if (format === 'json') {
+        return await response.json() as ResponseType<TFormat, T>;
+      } else {
+        return await response.text() as ResponseType<TFormat, T>;  // For 'bin' and 'hex', return raw text
+      }
+    } catch(error) {
+      let errorMessage: string | undefined
+
+      // Check if the error is due to timeout or other fetch-related issues
+      if (typeof error === 'string') {
+        errorMessage = error;
+        this.logger.error(error);
+      } else if (error instanceof DOMException && error.name === 'TimeoutError') {
+        // If error is an instance DOMException TimeoutError
+        errorMessage = 'Request timed out';
+        this.logger.error(`Request to ${endpoint} timed out after ${this.timeoutMs} ms`);
+      } else {
+        this.logger.error(`Unknown error occurred during request to ${endpoint}`);
+        throw new Error(`Unknown error: ${error}`);
+      }
+
+      // Always rethrow the error after logging
+      throw new Error(errorMessage);
+    }
+  }
+
+  /** Returns transaction details by txid. */
+  async getTransaction<TFormat extends formatOptions = 'json'>(
+    txid: string, format:TFormat = 'json' as TFormat
+  ) {
+    return this.fetchFromNode<TxDetails, TFormat>(`tx/${txid}.${format}`, format);
+  }
+
+  // getBlock overload signatures
+  // This is needed so the getBlock return type can depend on the 'includeTxDetails' boolean flag
+
+  /** Returns block data. Use includeTxDetails=true for full transaction objects. */
+  async getBlock<TFormat extends formatOptions = 'json'>(
+    blockhash: string, includeTxDetails: true, format?:TFormat
+  ): Promise<TFormat extends 'json' ? BlockInfoTxDetails : string>;
+
+  async getBlock<TFormat extends formatOptions = 'json'>(
+    blockhash: string, includeTxDetails: false, format?:TFormat
+  ): Promise<TFormat extends 'json' ? BlockInfoNoTxDetails : string>;
+
+  // getBlock Implementation
+  async getBlock<TFormat extends formatOptions = 'json'>(
+    blockhash: string, includeTxDetails: boolean, format:TFormat = 'json' as TFormat
+  ): Promise<any> {
+    const path = includeTxDetails ? 'block' : 'block/notxdetails';
+    return this.fetchFromNode(`${path}/${blockhash}.${format}`, format);
+  }
+
+  /** Returns block headers starting from a specific block hash. */
+  async getBlockHeaders<TFormat extends formatOptions = 'json'>(
+    count: number, blockhash: string, format:TFormat = 'json' as TFormat
+  ) {
+    return this.fetchFromNode<HeaderInfo, TFormat>(`headers/${count}/${blockhash}.${format}`, format);
+  }
+
+  /** Returns current chain state (network, sync progress, best block). */
+  async getChainInfo() {
+    return this.fetchFromNode<ChainInfo, 'json'>('chaininfo.json', 'json');
+  }
+
+  /** Queries UTXO set for specific outpoints. Outpoints format: "txid-vout". */
+  async getUTXOs<TFormat extends formatOptions = 'json'>(
+    checkmempool: boolean, outpoints: string[], format:TFormat = 'json' as TFormat
+  ) {
+    const path = (checkmempool ? 'checkmempool/' : '') + outpoints.join('/');
+    const endpoint = `getutxos/${path}.${format}`;
+    return this.fetchFromNode<UtxosInfo, TFormat>(endpoint, format);
+  }
+
+  /** Returns mempool statistics (size, bytes, fee rates). */
+  async getMempoolInfo() {
+    return this.fetchFromNode<MempoolInfo, 'json'>('mempool/info.json', 'json');
+  }
+
+  /** Returns all transactions currently in the mempool. */
+  async getMempoolContents() {
+    return this.fetchFromNode<MempoolContent, 'json'>('mempool/contents.json', 'json');
+  }
+
+  /** Returns block with bytecode pattern data (v29.0.0+). */
+  async getBlockWithPatterns(blockhash: string) {
+    return this.fetchFromNode<BlockInfoWithPatterns, 'json'>(`block/withpatterns/${blockhash}.json`, 'json');
+  }
+
+  /** Returns transaction with bytecode pattern data (v29.0.0+). */
+  async getTransactionWithPatterns(txid: string) {
+    return this.fetchFromNode<TxDetailsWithPatterns, 'json'>(`tx/withpatterns/${txid}.json`, 'json');
+  }
+}

package/src/rpcClient.ts

@@ -1,93 +1,100 @@
-import type { RpcClientConfig, RpcRequest } from "./interfaces/interfaces.js";
-import { getRandomId, validateAndConstructUrl } from "./utils/utils.js";
-import { RetryLimitExceededError } from "./utils/errors.js";
-
-export class BchnRpcClient {
-  private url: string
-  private rpcUser: string
-  private rpcPassword: string
-  
-  private maxRetries: number // number of retries before throwing an exception
-  private retryDelayMs: number // delay between each retry
-  private logger: typeof console // logger
-  private timeoutMs: number // max timeout for each retry
-
-  constructor(config: RpcClientConfig){
-    this.url = validateAndConstructUrl(config)
-    if(!config.rpcUser) throw new Error('Need to provide rpcUser in config')
-    if(!config.rpcPassword) throw new Error('Need to provide rpcPassword in config')
-    this.rpcUser = config.rpcUser;       
-    this.rpcPassword= config.rpcPassword;  
-
-    // optional config
-    this.maxRetries = config.maxRetries ?? 0;       
-    this.retryDelayMs= config.retryDelayMs ?? 100;  
-    this.logger = config.logger ?? console;         
-    this.timeoutMs = config.timeoutMs ?? 5000;      
-  }
-
-  async request<T extends RpcRequest>(
-    endpoint: T['method'],
-    ...params: T['params']
-  ): Promise<T['response']> {
-    const auth = Buffer.from(`${this.rpcUser}:${this.rpcPassword}`).toString('base64');
-    
-    // Retry logic
-    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
-      try {
-        // Send the request with a timeout and retries
-        const response = await fetch(this.url, {
-          method: 'POST',
-          headers: {
-            'Content-Type': 'application/json',
-            'Authorization': `Basic ${auth}`
-          },
-          body: JSON.stringify({ jsonrpc: '2.0', method: endpoint, params, id: getRandomId() }),
-          signal: AbortSignal.timeout(this.timeoutMs),
-        });
-  
-        const result = await response.json();
-  
-        // Handle response errors
-        if (!response.ok || result.error) {
-          throw new Error(`Error: ${result.error?.message || response.statusText}`);
-        }
-  
-        return result.result as T['response'];  // Return the result if successful
-  
-      } catch (error) {
-        let errorMessage: string | undefined
-        
-        // Check if the error is due to timeout or other fetch-related issues
-        if(typeof error == 'string'){
-          errorMessage = error
-          this.logger.error(error)
-        }
-        else if (error instanceof DOMException && error.name === 'TimeoutError') {
-          // If error is an instance DOMException TimeoutError
-          errorMessage = error.message
-          this.logger.error(`Request timed out after ${this.timeoutMs} ms`);
-        }
-        else if (error instanceof Error) {
-          // If error is an instance of Error, you can safely access its properties
-          errorMessage = error.message
-          this.logger.error(`Request failed with error: ${error.message}`);
-          
-        }
-  
-        // Retry if allowed
-        if (attempt < this.maxRetries) {
-          this.logger.warn(`Retrying request... (${attempt + 1}/${this.maxRetries})`);
-          await new Promise(res => setTimeout(res, this.retryDelayMs));  // Wait before retrying
-        } else {
-          // If no retries are left, throw the final error
-          throw new RetryLimitExceededError(`Request failed after ${this.maxRetries + 1} attempts: ${errorMessage}`);
-        }
-      }
-    }
-  
-    // This line ensures TypeScript is satisfied that a value will always be returned, but
-    // it should never be reached if the retries fail, as the last attempt should throw an error.
-    throw new Error('Request failed unexpectedly');
-  }
-}
+import type { RpcClientConfig, RpcRequest } from "./interfaces/interfaces.js";
+import { getRandomId, validateAndConstructUrl } from "./utils/utils.js";
+import { RetryLimitExceededError } from "./utils/errors.js";
+
+/** RPC client for full BCHN node interaction via JSON-RPC. */
+export class BchnRpcClient {
+  private url: string
+  private rpcUser: string
+  private rpcPassword: string
+
+  private maxRetries: number // number of retries before throwing an exception
+  private retryDelayMs: number // delay between each retry
+  private logger: typeof console // logger
+  private timeoutMs: number // max timeout for each retry
+
+  constructor(config: RpcClientConfig){
+    this.url = validateAndConstructUrl(config)
+    if(!config.rpcUser) throw new Error('Need to provide rpcUser in config')
+    if(!config.rpcPassword) throw new Error('Need to provide rpcPassword in config')
+    this.rpcUser = config.rpcUser;
+    this.rpcPassword= config.rpcPassword;
+
+    // optional config
+    this.maxRetries = config.maxRetries ?? 0;
+    this.retryDelayMs= config.retryDelayMs ?? 100;
+    this.logger = config.logger ?? console;
+    this.timeoutMs = config.timeoutMs ?? 5000;
+  }
+
+  /**
+   * Sends a typed RPC request to the BCHN node.
+   * @example
+   * const result = await client.request<GetBlockCount>("getblockcount");
+   * const block = await client.request<GetBlockVerbosity1>("getblock", hash, 1);
+   */
+  async request<T extends RpcRequest>(
+    endpoint: T['method'],
+    ...params: T['params']
+  ): Promise<T['response']> {
+    const auth = Buffer.from(`${this.rpcUser}:${this.rpcPassword}`).toString('base64');
+
+    // Retry logic
+    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+      try {
+        // Send the request with a timeout and retries
+        const response = await fetch(this.url, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            'Authorization': `Basic ${auth}`
+          },
+          body: JSON.stringify({ jsonrpc: '2.0', method: endpoint, params, id: getRandomId() }),
+          signal: AbortSignal.timeout(this.timeoutMs),
+        });
+
+        const result = await response.json();
+
+        // Handle response errors
+        if (!response.ok || result.error) {
+          throw new Error(`Error: ${result.error?.message || response.statusText}`);
+        }
+
+        return result.result as T['response'];  // Return the result if successful
+
+      } catch (error) {
+        let errorMessage: string | undefined
+
+        // Check if the error is due to timeout or other fetch-related issues
+        if(typeof error == 'string'){
+          errorMessage = error
+          this.logger.error(error)
+        }
+        else if (error instanceof DOMException && error.name === 'TimeoutError') {
+          // If error is an instance DOMException TimeoutError
+          errorMessage = error.message
+          this.logger.error(`Request timed out after ${this.timeoutMs} ms`);
+        }
+        else if (error instanceof Error) {
+          // If error is an instance of Error, you can safely access its properties
+          errorMessage = error.message
+          this.logger.error(`Request failed with error: ${error.message}`);
+
+        }
+
+        // Retry if allowed
+        if (attempt < this.maxRetries) {
+          this.logger.warn(`Retrying request... (${attempt + 1}/${this.maxRetries})`);
+          await new Promise(res => setTimeout(res, this.retryDelayMs));  // Wait before retrying
+        } else {
+          // If no retries are left, throw the final error
+          throw new RetryLimitExceededError(`Request failed after ${this.maxRetries + 1} attempts: ${errorMessage}`);
+        }
+      }
+    }
+
+    // This line ensures TypeScript is satisfied that a value will always be returned, but
+    // it should never be reached if the retries fail, as the last attempt should throw an error.
+    throw new Error('Request failed unexpectedly');
+  }
+}

package/src/utils/errors.ts

@@ -1,6 +1,6 @@
-export class RetryLimitExceededError extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = 'RetryLimitExceededError';
-  }
-}
+export class RetryLimitExceededError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'RetryLimitExceededError';
+  }
+}

package/src/utils/utils.ts

@@ -1,55 +1,55 @@
-import type {
-  RpcClientConfig,
-  RpcClientUrlConfig,
-  RpcClientHostConfig,
-} from "../interfaces/interfaces.js";
-
-export function getRandomId(): number {
-  return Math.floor(Math.random() * 100000);
-}
-
-// A utility function to validate and construct the URL from the RpcClientConfig object
-export function validateAndConstructUrl(config: RpcClientConfig): string {
-  let url: string
-  if (isUrlConfig(config)) {
-    url = validateUrl(config.url)
-  } else if (isHostConfig(config)) {
-    const { protocol, host, port } = config;
-    if (protocol !== 'http' && protocol !== 'https') {
-      throw new Error("Protocol should be 'http' or 'https'");
-    }
-    url = validateUrl(`${protocol}://${host}:${port}`)
-  } else {
-    throw new Error('Invalid configuration: Either provide the url or protocol/host/port');
-  }
-  return url
-}
-
-// A utility function to validate a URL
-export function validateUrl(url: string) {
-  if(!url) throw new Error('URL is required');
-  try {
-    new URL(url);
-  } catch (err) {
-    throw new Error('Invalid URL format');
-  }
-  return url
-}
-
-// Type guard to check if the config is RpcClientUrlConfig
-function isUrlConfig(config: RpcClientConfig): config is RpcClientUrlConfig {
-  return 'url' in config;
-}
-
-// Type guard to check if the config is RpcClientHostConfig
-function isHostConfig(config: RpcClientConfig): config is RpcClientHostConfig {
-  return 'protocol' in config && 'hostname' in config && 'port' in config;
-}
-
-export enum BchnNetworkPort {
-  Mainnet = 8332,
-  Testnet = 18332,
-  Testnet4 = 28332,
-  Scalenet = 38332,
-  Regtest = 18443
-}
+import type {
+  RpcClientConfig,
+  RpcClientUrlConfig,
+  RpcClientHostConfig,
+} from "../interfaces/interfaces.js";
+
+export function getRandomId(): number {
+  return Math.floor(Math.random() * 100000);
+}
+
+// A utility function to validate and construct the URL from the RpcClientConfig object
+export function validateAndConstructUrl(config: RpcClientConfig): string {
+  let url: string
+  if (isUrlConfig(config)) {
+    url = validateUrl(config.url)
+  } else if (isHostConfig(config)) {
+    const { protocol, host, port } = config;
+    if (protocol !== 'http' && protocol !== 'https') {
+      throw new Error("Protocol should be 'http' or 'https'");
+    }
+    url = validateUrl(`${protocol}://${host}:${port}`)
+  } else {
+    throw new Error('Invalid configuration: Either provide the url or protocol/host/port');
+  }
+  return url
+}
+
+// A utility function to validate a URL
+export function validateUrl(url: string) {
+  if(!url) throw new Error('URL is required');
+  try {
+    new URL(url);
+  } catch (err) {
+    throw new Error('Invalid URL format');
+  }
+  return url
+}
+
+// Type guard to check if the config is RpcClientUrlConfig
+function isUrlConfig(config: RpcClientConfig): config is RpcClientUrlConfig {
+  return 'url' in config;
+}
+
+// Type guard to check if the config is RpcClientHostConfig
+function isHostConfig(config: RpcClientConfig): config is RpcClientHostConfig {
+  return 'protocol' in config && 'hostname' in config && 'port' in config;
+}
+
+export enum BchnNetworkPort {
+  Mainnet = 8332,
+  Testnet = 18332,
+  Testnet4 = 28332,
+  Scalenet = 38332,
+  Regtest = 18443
+}