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

package/src/index.ts

@@ -1,4 +1,4 @@
-export * from './interfaces/interfaces.js'
-export * from './interfaces/rpcInterfaces/index.js'
-export { BchnRpcClient } from './rpcClient.js'
+export * from './interfaces/interfaces.js'
+export * from './interfaces/rpcInterfaces/index.js'
+export { BchnRpcClient } from './rpcClient.js'
 export { BchnRestClient } from './restClient.js'

package/src/interfaces/interfaces.ts

@@ -1,87 +1,97 @@
-export interface BaseRpcClientConfig {
-  rpcUser: string;
-  rpcPassword: string;
-  maxRetries?: number;
-  retryDelayMs?: number;
-  logger?: typeof console ;
-  timeoutMs?: number;
-}
-
-export interface RpcClientUrlConfig extends BaseRpcClientConfig {
-  url: string;
-}
-
-export interface RpcClientHostConfig extends BaseRpcClientConfig {
-  protocol: 'http' | 'https';
-  host: string;
-  port: number;
-}
-
-export type RpcClientConfig = RpcClientUrlConfig | RpcClientHostConfig
-
-export type RPCParameter = string | number | boolean | undefined | object;
-declare type RequestResponse = object | string | number | boolean | null | RequestResponse[];
-
-export interface RpcRequest {
-  method: string;
-  params: Array<RPCParameter>;
-  response: RequestResponse;
-}
-
-export interface RestClientConfig {
-  url: string;
-  logger?: typeof console ;
-  timeoutMs?: number;
-}
-
-
-export type formatOptions = 'bin' | 'hex' | 'json'
-
-// Conditional type to return the appropriate data type based on format
-export type ResponseType<TFormat extends formatOptions, TJson> = 
-  TFormat extends 'json' ? TJson :
-  TFormat extends 'hex' | 'bin' ? string :
-  never;
-
-// General interfaces used in both REST & RPC endpoints
-export interface Transaction {
-  txid: string;
-  hash: string;
-  size: number;
-  version: number;
-  locktime: number;
-  vin: TransactionInput[];
-  vout: TransactionOutput[];
-}
-
-export interface TransactionInput {
-  txid: string;
-  vout: number;
-  scriptSig: {
-    asm: string;
-    hex: string;
-  };
-  sequence: number;
-}
-
-export interface TransactionOutput {
-  value: number;
-  n: number;
-  scriptPubKey: {
-    asm: string;
-    hex: string;
-    reqSigs: number;
-    type: string;
-    addresses: string[];
-    tokenData: TokenData;
-  }
-}
-
-export interface TokenData {
-  category : string;
-  amount: string;
-  nft?: {
-    capability: 'none' | 'mutable' | 'minting';
-    commitment: string;
-  }
+/** Base RPC client authentication and connection settings. */
+export interface BaseRpcClientConfig {
+  rpcUser: string;
+  rpcPassword: string;
+  maxRetries?: number;
+  retryDelayMs?: number;
+  logger?: typeof console ;
+  timeoutMs?: number;
+}
+
+/** RPC client config using a full URL (e.g., "http://localhost:8332"). */
+export interface RpcClientUrlConfig extends BaseRpcClientConfig {
+  url: string;
+}
+
+/** RPC client config using separate host, port, and protocol. */
+export interface RpcClientHostConfig extends BaseRpcClientConfig {
+  protocol: 'http' | 'https';
+  host: string;
+  port: number;
+}
+
+/** RPC client configuration - either URL-based or host-based. */
+export type RpcClientConfig = RpcClientUrlConfig | RpcClientHostConfig
+
+/** Valid parameter types for RPC method calls. */
+export type RPCParameter = string | number | boolean | undefined | object;
+declare type RequestResponse = object | string | number | boolean | null | RequestResponse[];
+
+/** Base interface for all RPC request types with method, params, and response. */
+export interface RpcRequest {
+  method: string;
+  params: Array<RPCParameter>;
+  response: RequestResponse;
+}
+
+/** REST client configuration. */
+export interface RestClientConfig {
+  url: string;
+  logger?: typeof console ;
+  timeoutMs?: number;
+}
+
+/** REST endpoint response format options. */
+export type formatOptions = 'bin' | 'hex' | 'json'
+
+/** Conditional return type based on format: JSON returns parsed object, hex/bin return string. */
+export type ResponseType<TFormat extends formatOptions, TJson> =
+  TFormat extends 'json' ? TJson :
+  TFormat extends 'hex' | 'bin' ? string :
+  never;
+
+/** Base transaction structure used in both REST and RPC responses. */
+export interface Transaction {
+  txid: string;
+  hash: string;
+  size: number;
+  version: number;
+  locktime: number;
+  vin: TransactionInput[];
+  vout: TransactionOutput[];
+}
+
+/** Transaction input referencing a previous output (UTXO). */
+export interface TransactionInput {
+  txid: string;
+  vout: number;
+  scriptSig: {
+    asm: string;
+    hex: string;
+  };
+  sequence: number;
+}
+
+/** Transaction output with value and locking script. */
+export interface TransactionOutput {
+  value: number;
+  n: number;
+  scriptPubKey: {
+    asm: string;
+    hex: string;
+    reqSigs: number;
+    type: string;
+    addresses: string[];
+    tokenData: TokenData;
+  }
+}
+
+/** CashTokens data attached to a UTXO (fungible amount and/or NFT). */
+export interface TokenData {
+  category : string;
+  amount: string;
+  nft?: {
+    capability: 'none' | 'mutable' | 'minting';
+    commitment: string;
+  }
 }

package/src/interfaces/restInterfaces/interfaces.ts

@@ -1,117 +1,236 @@
-import type { Transaction } from "../interfaces.js";
-
-export interface BlockInfoNoTxDetails {
-  hash: string;
-  confirmations: number;
-  size: number;
-  height: number;
-  version: number;
-  versionHex: string;
-  merkleroot: string;
-  tx : string[]
-  time: number;
-  mediantime: number;
-  nonce: number;
-  bits: string;
-  difficulty: number;
-  chainwork: string;
-  nTx: number;
-  previousblockhash: string;
-  nextblockhash: string;
-  ablastate: {
-    epsilon: number;
-    beta: number;
-    blocksize: number;
-    blocksizelimit: number;
-    nextblocksizelimit: number;
-  }
-}
-
-export interface BlockInfoTxDetails extends Omit<BlockInfoNoTxDetails, 'tx'>{
-  tx: Transaction[]
-}
-
-export interface HeaderInfo {
-  hash: string;
-  confirmations: number;
-  height: number;
-  version: number;
-  versionHex: string;
-  merkleroot: string;
-  time: number;
-  mediantime: number;
-  nonce: number;
-  bits: string;
-  difficulty: number;
-  chainwork: string;
-  nTx: number;
-  previousblockhash: string;
-  nextblockhash: string;
-  ablastate: {
-    epsilon: number;
-    beta: number;
-    blocksize: number;
-    blocksizelimit: number;
-    nextblocksizelimit: number;
-  }
-}
-
-export interface ChainInfo {
-  chain: 'main' | 'test' | 'regtest';
-  blocks: number;
-  headers: number;
-  bestblockhash: string;
-  difficulty: number;
-  mediantime: number;
-  verificationprogress: number;
-  initialblockdownload: boolean,
-  chainwork: string;
-  size_on_disk: number;
-  pruned: boolean;
-  warnings: string;
-}
-
-export interface UtxosInfo {
-  chaintipHash: string;
-  chainHeight: number;
-  utxos: {
-    scriptPubKey: {
-      addresses: string[];
-      type: string;
-      hex: string;
-      reqSigs: number;
-      asm: string;
-    },
-    value: number
-    height: number
-    txvers: number
-  }[]
-  bitmap: string;
-}
-
-export interface MempoolInfo {
-  loaded: boolean;
-  size: number;
-  bytes: number;
-  usage: number;
-  maxmempool: number;
-  mempoolminfee: number;
-  minrelaytxfee: number;
-}
-
-export interface MempoolContent {
-  [txid: string]: {
-    fees: {
-      base: number;
-      modified: number;
-    },
-    size: number;
-    time: number;
-    depends: string[];
-    spentby: string[];
-  }
-}
-
-export interface TxDetails extends Transaction {
-  blockhash: string;
+import type { Transaction } from "../interfaces.js";
+
+/** Adaptive Block Limit Algorithm state (activated May 2024). */
+export interface AblaState {
+  epsilon: number;
+  beta: number;
+  blocksize: number;
+  blocksizelimit: number;
+  nextblocksizelimit: number;
+}
+
+/**
+ * Base block info fields shared across response types.
+ * @note `previousblockhash` not present on genesis block (height 0).
+ * @note `nextblockhash` not present on chain tip.
+ */
+interface BlockInfoBase {
+  hash: string;
+  confirmations: number;
+  size: number;
+  height: number;
+  version: number;
+  versionHex: string;
+  merkleroot: string;
+  time: number;
+  mediantime: number;
+  nonce: number;
+  bits: string;
+  difficulty: number;
+  chainwork: string;
+  nTx: number;
+  previousblockhash: string;
+  nextblockhash: string;
+}
+
+/** Block info with tx IDs only - works for any block. */
+export interface BlockInfoNoTxDetails extends BlockInfoBase {
+  tx: string[];
+  ablastate?: AblaState;
+}
+
+/** Block info with tx IDs only - for blocks before ABLA activation (May 2024). */
+export interface BlockInfoNoTxDetailsPreAbla extends BlockInfoBase {
+  tx: string[];
+}
+
+/** Block info with tx IDs only - for blocks after ABLA activation (May 2024). */
+export interface BlockInfoNoTxDetailsPostAbla extends BlockInfoBase {
+  tx: string[];
+  ablastate: AblaState;
+}
+
+/** Block info with full transaction objects - works for any block. */
+export interface BlockInfoTxDetails extends BlockInfoBase {
+  tx: Transaction[];
+  ablastate?: AblaState;
+}
+
+/** Block info with full transaction objects - for blocks before ABLA activation (May 2024). */
+export interface BlockInfoTxDetailsPreAbla extends BlockInfoBase {
+  tx: Transaction[];
+}
+
+/** Block info with full transaction objects - for blocks after ABLA activation (May 2024). */
+export interface BlockInfoTxDetailsPostAbla extends BlockInfoBase {
+  tx: Transaction[];
+  ablastate: AblaState;
+}
+
+/**
+ * Base header info fields shared across response types.
+ * @note `previousblockhash` not present on genesis block (height 0).
+ * @note `nextblockhash` not present on chain tip.
+ */
+interface HeaderInfoBase {
+  hash: string;
+  confirmations: number;
+  height: number;
+  version: number;
+  versionHex: string;
+  merkleroot: string;
+  time: number;
+  mediantime: number;
+  nonce: number;
+  bits: string;
+  difficulty: number;
+  chainwork: string;
+  nTx: number;
+  previousblockhash: string;
+  nextblockhash: string;
+}
+
+/** Block header info - works for any block. */
+export interface HeaderInfo extends HeaderInfoBase {
+  ablastate?: AblaState;
+}
+
+/** Block header info - for blocks before ABLA activation (May 2024). */
+export interface HeaderInfoPreAbla extends HeaderInfoBase {}
+
+/** Block header info - for blocks after ABLA activation (May 2024). */
+export interface HeaderInfoPostAbla extends HeaderInfoBase {
+  ablastate: AblaState;
+}
+
+/** Current blockchain state and synchronization status. */
+export interface ChainInfo {
+  chain: 'main' | 'test' | 'regtest';
+  blocks: number;
+  headers: number;
+  bestblockhash: string;
+  difficulty: number;
+  mediantime: number;
+  verificationprogress: number;
+  initialblockdownload: boolean,
+  chainwork: string;
+  size_on_disk: number;
+  pruned: boolean;
+  warnings: string;
+}
+
+/** UTXO set query result with bitmap for checked outpoints. */
+export interface UtxosInfo {
+  chaintipHash: string;
+  chainHeight: number;
+  utxos: {
+    scriptPubKey: {
+      addresses: string[];
+      type: string;
+      hex: string;
+      reqSigs: number;
+      asm: string;
+    },
+    value: number
+    height: number
+    txvers: number
+  }[]
+  bitmap: string;
+}
+
+/** Mempool configuration and size statistics. */
+export interface MempoolInfo {
+  loaded: boolean;
+  size: number;
+  bytes: number;
+  usage: number;
+  maxmempool: number;
+  mempoolminfee: number;
+  minrelaytxfee: number;
+  permitbaremultisig: boolean;
+  maxdatacarriersize: number;
+}
+
+/** Mempool contents indexed by txid with fee and dependency info. */
+export interface MempoolContent {
+  [txid: string]: {
+    fees: {
+      base: number;
+      modified: number;
+    },
+    size: number;
+    time: number;
+    depends: string[];
+    spentby: string[];
+  }
+}
+
+/** Transaction with block hash (for confirmed transactions). */
+export interface TxDetails extends Transaction {
+  blockhash: string;
+}
+
+/** Script fingerprint and pattern info for bytecode analysis (v29.0.0+). */
+export interface ByteCodePattern {
+  fingerprint: string;
+  pattern: string;
+  patternArgsInfo?: string[];
+}
+
+/** Script with optional bytecode pattern metadata (v29.0.0+). */
+export interface ScriptPubKeyWithPattern {
+  asm: string;
+  hex: string;
+  type: string;
+  address?: string;
+  byteCodePattern?: ByteCodePattern;
+}
+
+/** Transaction input with prevout and pattern info (v29.0.0+). */
+export interface TransactionInputWithPattern {
+  txid: string;
+  vout: number;
+  scriptSig: {
+    asm: string;
+    hex: string;
+  };
+  sequence: number;
+  prevout?: {
+    generated: boolean;
+    height: number;
+    value: number;
+    scriptPubKey: ScriptPubKeyWithPattern;
+  };
+  redeemScript?: {
+    asm: string;
+    hex: string;
+    type: string;
+    byteCodePattern?: ByteCodePattern;
+    p2shType?: string;
+  };
+}
+
+/** Transaction output with pattern-enabled scriptPubKey (v29.0.0+). */
+export interface TransactionOutputWithPattern {
+  value: number;
+  n: number;
+  scriptPubKey: ScriptPubKeyWithPattern;
+}
+
+/** Transaction with bytecode patterns and optional fee (v29.0.0+). */
+export interface TxDetailsWithPatterns {
+  txid: string;
+  hash: string;
+  size: number;
+  version: number;
+  locktime: number;
+  vin: TransactionInputWithPattern[];
+  vout: TransactionOutputWithPattern[];
+  blockhash: string;
+  fee?: number;
+}
+
+/** Block with pattern-enhanced transactions (v29.0.0+). */
+export interface BlockInfoWithPatterns extends Omit<BlockInfoNoTxDetails, 'tx'> {
+  tx: TxDetailsWithPatterns[];
 }