@mr-zwets/bchn-api-wrapper 1.0.1

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+## v1.0.1
+
+❗️ Fix for huge list of unneeded dependencies accidentally introduced by `nmp@9.5.1` on `npm init`
+
+## v1.0.0
+
+First Release 🥳

package/README.md

@@ -0,0 +1,129 @@
+# 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
+```

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/interfaces/interfaces.d.ts

@@ -0,0 +1,70 @@
+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';
+export type ResponseType<TFormat extends formatOptions, TJson> = TFormat extends 'json' ? TJson : TFormat extends 'hex' | 'bin' ? string : never;
+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;
+    };
+}
+export {};

package/dist/interfaces/interfaces.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,109 @@
+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;
+}

package/dist/interfaces/restInterfaces/interfaces.js

@@ -0,0 +1 @@
+export {};