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

package/.claude/settings.local.json

@@ -0,0 +1,8 @@
+{
+  "permissions": {
+    "allow": [
+      "WebFetch(domain:github.com)",
+      "WebFetch(domain:docs.bitcoincashnode.org)"
+    ]
+  }
+}

package/.github/workflows/ci.yaml

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Build
+        run: pnpm build
+
+      - name: Run tests
+        run: pnpm test run

package/CLAUDE.md

@@ -0,0 +1,70 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Build & Test Commands
+
+```bash
+pnpm build          # Compile TypeScript to dist/
+pnpm test           # Run all tests with Vitest
+pnpm test <file>    # Run a specific test file
+```
+
+## Architecture
+
+TypeScript library providing type-safe wrappers for Bitcoin Cash Node (BCHN) JSON-RPC and REST interfaces. Types compatible with **BCHN v29.0.0**. Zero runtime dependencies.
+
+### Two Client Classes
+
+**BchnRestClient** (`src/restClient.ts`)
+- Wraps 11 REST endpoints for read-only blockchain access-
+- Class with dedicated methods for each endpoint
+- Supports format options (`json`, `hex`, `bin`) via conditional return types
+- Uses function overloads for type-safe returns based on parameters (e.g., `getBlock` with `includeTxDetails`)
+
+**BchnRpcClient** (`src/rpcClient.ts`)
+- Wraps 136 RPC commands for full node interaction
+- Single generic `request<T extends RpcRequest>()` method
+- Type safety achieved through discriminated union interfaces
+- Each RPC command interface defines: `method`, `params[]`, and `response` type
+
+### Interface Organization
+
+```
+src/interfaces/
+├── interfaces.ts              # Config types, RpcRequest base, shared types
+├── restInterfaces/            # REST response types
+└── rpcInterfaces/             # 136 RPC command interfaces across 9 files
+    ├── blockchain.ts          # 33 commands
+    ├── wallet.ts              # 52 commands
+    ├── rawtransactions.ts
+    ├── network.ts             # 14 commands
+    ├── mining.ts
+    ├── control.ts             # 6 commands
+    ├── util.ts
+    ├── generating.ts
+    └── zmq.ts
+```
+
+### RPC Type Pattern
+
+RPC interfaces follow this pattern for full type inference:
+
+```typescript
+export interface GetBlockVerbosity1 extends GetBlockBase {
+  params: [blockhash: string, verbosity?: 1 | true];
+  response: { hash: string; /* ... */ };
+}
+
+// Usage - params and response are fully typed:
+const result = await rpcClient.request<GetBlockVerbosity1>("getblock", hash, 1);
+```
+
+### Configuration Types
+
+- `RpcClientConfig`: Supports URL-based (`{url, rpcUser, rpcPassword}`) or host-based (`{protocol, host, port, rpcUser, rpcPassword}`) configuration
+- `RestClientConfig`: Requires `url`, optional `logger` and `timeoutMs`
+
+### Testing
+
+Tests use Vitest with MSW (Mock Service Worker) for HTTP interception. Mock server setup is in `test/setupTests.ts`.

package/README.md

@@ -1,129 +1,121 @@
-# BCHN-API-Wrapper 
-
-This library is a Typescript wrapper for interacting with the Bitcoin Cash Node (BCHN) RPC and REST interfaces. 
-
-## Features
-
-The library is a simple wrapper for using the BCHN REST and RPC-endpoints in a type-safe way.
-
-The library is designed to be easy to use and get started with.
-
-The library has good documentation, automated tests and zero dependencies.
-
-## Details
-
-The `BchnRestClient` uses a class with unique methods for each of the endpoints.
-
-The `BchnRpcClient` uses a request function which uses generics to type arguments and responses.
-
-The **REST API** is ideal for **read-only** access to general blockchain information such as transactions, blocks, and UTXO data. In contrast, the **RPC API** allows for **full interaction** with the Bitcoin Cash node, including managing the built-in wallet, sending transactions, performing mining operations, and issuing control commands like pruning or stopping the node. While the REST API provides 9 endpoints, the RPC API offers a much broader set of 136 commands.
-
-## Configuration
-
-To use the RPC and REST APIs on your BCHN node, you need to enable them in your node's configuration file.
-
-<details>
-  <summary>BCHN Configuration</summary>
-  In the BCHN '.conf' file add the following settings:
-
-  ```bash
-    server=1
-    rest=1
-    txindex=1
-    rpcuser=rpcuser
-    rpcpassword=rpcpassword
-    rpcallowip=127.0.0.1
-    rpcport=8332
-  ```
-
-  To learn more about the `.conf` settings, see the [BCHN documentation](https://docs.bitcoincashnode.org/doc/bitcoin-conf/).
-</details>
-
-Note that the REST-endpoints can be made public, but the RPC-endpoints should never be made public. If you want to use the RPC-endpoints of your own node remotely, you need a secure connection using SSL/TLS to encrypt your communication and protect your credentials and data from being exposed. Additionally, ensure you have strong, unique RPC credentials (username and password) set in your node's configuration file.
-
-## Install
-
-Install the Bchn-API-Wrapper from NPM with:
-
-```bash
-npm install @mr-zwets/bchn-api-wrapper
-```
-
-or using yarn 
-
-```bash
-yarn add @mr-zwets/bchn-api-wrapper
-```
-
-## REST usage
-
-The `BchnRestClient` is a wrapper over the 9 BCHN REST-endpoints. For the list of the BCHN REST-endpoints see the [REST documentation](https://docs.bitcoincashnode.org/doc/REST-interface/).
-
-The `RestClientConfig` object accepts optional parameters for `logger` & `timeoutMs`
-
-### REST example
-
-```ts
-import { BchnRestClient, RestClientConfig } from 'bchn-api-wrapper'
-
-// Create the RestClientConfig
-const clientOptions: RestClientConfig = {
-  url: "http://localhost:8332",
-}
-// Instantiate the REST client to query your BCHN node
-const restClient = new BchnRestClient(clientOptions)
-
-// Get the latest blockhash
-const chainInfo = await restClient.getChainInfo()
-const latestBlockHash = chainInfo.bestblockhash
-console.log(`The latest blockhash is ${latestBlockHash}`)
-
-// Get block info with includeTxDetails flag
-const fullBlockInfo = await restClient.getBlock(latestBlockHash, true)
-console.log(JSON.stringify(fullBlockInfo))
-```
-
-## RPC usage
-
-The `BchnRpcClient` is a thin type-wrapper over the actual RPC endpoints, with request interfaces for each endpoint. For a complete list of all BCHN RPC-endpoints see the [RPC documentation](https://docs.bitcoincashnode.org/doc/json-rpc/).
-
-The `RpcClientConfig` object accepts optional parameters for `logger`, `timeoutMs`, `retryDelayMs` & `maxRetries`
-
-The library does not currently support making batched RPC requests.
-
-### RPC example
-
-```ts
-import { BchnRpcClient, RpcClientConfig, GetBestBlockHash, GetBlockVerbosity1 } from 'bchn-api-wrapper'
-
-// Create the RpcClientConfig
-const clientOptions: RpcClientConfig = {
-  url: "http://localhost:8332",
-  rpcUser: "rpcUser",
-  rpcPassword: "rpcPassword"
-}
-// Instantiate the RPC client to query your BCHN node
-const rpcClient = new BchnRpcClient(clientOptions)
-
-// Get the latest blockhash
-const latestBlockHash = await rpcClient.request<GetBestBlockHash>("getbestblockhash")
-console.log(`The latest blockhash is ${latestBlockHash}`)
-
-// Get verbosity1 info about the latest block contents
-const fullBlockInfo = await rpcClient.request<GetBlockVerbosity1>("getblock", latestBlockHash, 1)
-console.log(JSON.stringify(fullBlockInfo))
-```
-
-### Run Tests
-
-The library has automated tests using vitest, run the testing suite with:
-
-```bash
-npm run test
-```
-
-or using yarn:
-
-```bash
-yarn test
-```
+# BCHN-API-Wrapper
+
+This library is a Typescript wrapper for interacting with the Bitcoin Cash Node (BCHN) RPC and REST interfaces.
+
+## Compatibility
+
+RPC and REST interface types compatible with **BCHN v29.0.0**.
+
+## Features
+
+The library is a simple wrapper for using the BCHN REST and RPC-endpoints in a type-safe way.
+
+The library is designed to be easy to use and get started with.
+
+The library has good documentation, automated tests and zero dependencies.
+
+## Details
+
+The `BchnRestClient` uses a class with unique methods for each of the endpoints.
+
+The `BchnRpcClient` uses a request function which uses generics to type arguments and responses.
+
+The **REST API** is ideal for **read-only** access to general blockchain information such as transactions, blocks, and UTXO data. In contrast, the **RPC API** allows for **full interaction** with the Bitcoin Cash node, including managing the built-in wallet, sending transactions, performing mining operations, and issuing control commands like pruning or stopping the node. While the REST API provides 11 endpoints, the RPC API offers a much broader set of 136 commands.
+
+## Configuration
+
+To use the RPC and REST APIs on your BCHN node, you need to enable them in your node's configuration file.
+
+<details>
+  <summary>BCHN Configuration</summary>
+  In the BCHN '.conf' file add the following settings:
+
+  ```bash
+    server=1
+    rest=1
+    txindex=1
+    rpcuser=rpcuser
+    rpcpassword=rpcpassword
+    rpcallowip=127.0.0.1
+    rpcport=8332
+  ```
+
+  To learn more about the `.conf` settings, see the [BCHN documentation](https://docs.bitcoincashnode.org/doc/bitcoin-conf/).
+</details>
+
+Note that the REST-endpoints can be made public, but the RPC-endpoints should never be made public. If you want to use the RPC-endpoints of your own node remotely, you need a secure connection using SSL/TLS to encrypt your communication and protect your credentials and data from being exposed. Additionally, ensure you have strong, unique RPC credentials (username and password) set in your node's configuration file.
+
+## Install
+
+Install the BCHN-API-Wrapper from NPM with:
+
+```bash
+pnpm install @mr-zwets/bchn-api-wrapper
+```
+
+## REST usage
+
+The `BchnRestClient` is a wrapper over the 11 BCHN REST-endpoints. For the list of the BCHN REST-endpoints see the [REST documentation](https://docs.bitcoincashnode.org/doc/REST-interface/).
+
+The `RestClientConfig` object accepts optional parameters for `logger` & `timeoutMs`
+
+### REST example
+
+```ts
+import { BchnRestClient, RestClientConfig } from 'bchn-api-wrapper'
+
+// Create the RestClientConfig
+const clientOptions: RestClientConfig = {
+  url: "http://localhost:8332",
+}
+// Instantiate the REST client to query your BCHN node
+const restClient = new BchnRestClient(clientOptions)
+
+// Get the latest blockhash
+const chainInfo = await restClient.getChainInfo()
+const latestBlockHash = chainInfo.bestblockhash
+console.log(`The latest blockhash is ${latestBlockHash}`)
+
+// Get block info with includeTxDetails flag
+const fullBlockInfo = await restClient.getBlock(latestBlockHash, true)
+console.log(JSON.stringify(fullBlockInfo))
+```
+
+## RPC usage
+
+The `BchnRpcClient` is a thin type-wrapper over the actual RPC endpoints, with request interfaces for each endpoint. For a complete list of all BCHN RPC-endpoints see the [RPC documentation](https://docs.bitcoincashnode.org/doc/json-rpc/).
+
+The `RpcClientConfig` object accepts optional parameters for `logger`, `timeoutMs`, `retryDelayMs` & `maxRetries`
+
+The library does not currently support making batched RPC requests.
+
+### RPC example
+
+```ts
+import { BchnRpcClient, RpcClientConfig, GetBestBlockHash, GetBlockVerbosity1 } from 'bchn-api-wrapper'
+
+// Create the RpcClientConfig
+const clientOptions: RpcClientConfig = {
+  url: "http://localhost:8332",
+  rpcUser: "rpcUser",
+  rpcPassword: "rpcPassword"
+}
+// Instantiate the RPC client to query your BCHN node
+const rpcClient = new BchnRpcClient(clientOptions)
+
+// Get the latest blockhash
+const latestBlockHash = await rpcClient.request<GetBestBlockHash>("getbestblockhash")
+console.log(`The latest blockhash is ${latestBlockHash}`)
+
+// Get verbosity1 info about the latest block contents
+const fullBlockInfo = await rpcClient.request<GetBlockVerbosity1>("getblock", latestBlockHash, 1)
+console.log(JSON.stringify(fullBlockInfo))
+```
+
+### Run Tests
+
+The library has automated tests using vitest, run the testing suite with:
+
+```bash
+pnpm run test
+```

package/dist/interfaces/interfaces.d.ts

@@ -1,3 +1,4 @@
+/** Base RPC client authentication and connection settings. */
 export interface BaseRpcClientConfig {
     rpcUser: string;
     rpcPassword: string;
@@ -6,29 +7,38 @@ export interface BaseRpcClientConfig {
     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;
@@ -38,6 +48,7 @@ export interface Transaction {
     vin: TransactionInput[];
     vout: TransactionOutput[];
 }
+/** Transaction input referencing a previous output (UTXO). */
 export interface TransactionInput {
     txid: string;
     vout: number;
@@ -47,6 +58,7 @@ export interface TransactionInput {
     };
     sequence: number;
 }
+/** Transaction output with value and locking script. */
 export interface TransactionOutput {
     value: number;
     n: number;
@@ -59,6 +71,7 @@ export interface TransactionOutput {
         tokenData: TokenData;
     };
 }
+/** CashTokens data attached to a UTXO (fungible amount and/or NFT). */
 export interface TokenData {
     category: string;
     amount: string;

package/dist/interfaces/restInterfaces/interfaces.d.ts

@@ -1,5 +1,18 @@
 import type { Transaction } from "../interfaces.js";
-export interface BlockInfoNoTxDetails {
+/** 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;
@@ -7,7 +20,6 @@ export interface BlockInfoNoTxDetails {
     version: number;
     versionHex: string;
     merkleroot: string;
-    tx: string[];
     time: number;
     mediantime: number;
     nonce: number;
@@ -17,18 +29,41 @@ export interface BlockInfoNoTxDetails {
     nTx: number;
     previousblockhash: string;
     nextblockhash: string;
-    ablastate: {
-        epsilon: number;
-        beta: number;
-        blocksize: number;
-        blocksizelimit: number;
-        nextblocksizelimit: number;
-    };
 }
-export interface BlockInfoTxDetails extends Omit<BlockInfoNoTxDetails, 'tx'> {
+/** 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;
 }
-export interface HeaderInfo {
+/**
+ * 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;
@@ -44,14 +79,19 @@ export interface HeaderInfo {
     nTx: number;
     previousblockhash: string;
     nextblockhash: string;
-    ablastate: {
-        epsilon: number;
-        beta: number;
-        blocksize: number;
-        blocksizelimit: number;
-        nextblocksizelimit: number;
-    };
 }
+/** 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;
@@ -66,6 +106,7 @@ export interface ChainInfo {
     pruned: boolean;
     warnings: string;
 }
+/** UTXO set query result with bitmap for checked outpoints. */
 export interface UtxosInfo {
     chaintipHash: string;
     chainHeight: number;
@@ -83,6 +124,7 @@ export interface UtxosInfo {
     }[];
     bitmap: string;
 }
+/** Mempool configuration and size statistics. */
 export interface MempoolInfo {
     loaded: boolean;
     size: number;
@@ -91,7 +133,10 @@ export interface MempoolInfo {
     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: {
@@ -104,6 +149,67 @@ export interface MempoolContent {
         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[];
+}
+export {};