@bsv/wallet-toolbox 1.5.20 → 1.6.1

package/src/services/providers/WhatsOnChain.ts

@@ -1,18 +1,30 @@
 import { Beef, HexString, Utils, WhatsOnChainConfig } from '@bsv/sdk'
-import { asArray, asString, doubleSha256BE, sdk, Services, validateScriptHash, wait } from '../../index.client'
 import { convertProofToMerklePath } from '../../utility/tscProofToMerklePath'
 import SdkWhatsOnChain from './SdkWhatsOnChain'
-import { parseWalletOutpoint, ReqHistoryNote } from '../../sdk'
-
-/**
- *
- */
-export class WhatsOnChain extends SdkWhatsOnChain {
-  services: Services
-
-  constructor(chain: sdk.Chain = 'main', config: WhatsOnChainConfig = {}, services?: Services) {
+import { Chain, ReqHistoryNote } from '../../sdk/types'
+import {
+  BlockHeader,
+  BsvExchangeRate,
+  GetMerklePathResult,
+  GetRawTxResult,
+  GetScriptHashHistoryResult,
+  GetStatusForTxidsResult,
+  GetUtxoStatusOutputFormat,
+  GetUtxoStatusResult,
+  PostBeefResult,
+  PostTxResultForTxid,
+  WalletServices
+} from '../../sdk/WalletServices.interfaces'
+import { WERR_BAD_REQUEST, WERR_INTERNAL, WERR_INVALID_OPERATION, WERR_INVALID_PARAMETER } from '../../sdk/WERR_errors'
+import { WalletError } from '../../sdk/WalletError'
+import { doubleSha256BE, wait } from '../../utility/utilityHelpers'
+import { asArray, asString } from '../../utility/utilityHelpers.noBuffer'
+import { Services, validateScriptHash } from '../Services'
+import { parseWalletOutpoint } from '../../sdk/validationHelpers'
+
+export class WhatsOnChainNoServices extends SdkWhatsOnChain {
+  constructor(chain: Chain = 'main', config: WhatsOnChainConfig = {}) {
     super(chain, config)
-    this.services = services || new Services(chain)
   }
 
   /**
@@ -36,8 +48,8 @@ export class WhatsOnChain extends SdkWhatsOnChain {
    * result for an unknown txid:
    *     [{"txid":"6815f8014db74eab8b7f75925c68929597f1d97efa970109d990824c25e5e62c","error":"unknown"}]
    */
-  async getStatusForTxids(txids: string[]): Promise<sdk.GetStatusForTxidsResult> {
-    const r: sdk.GetStatusForTxidsResult = {
+  async getStatusForTxids(txids: string[]): Promise<GetStatusForTxidsResult> {
+    const r: GetStatusForTxidsResult = {
       name: 'WoC',
       status: 'error',
       error: undefined,
@@ -56,7 +68,7 @@ export class WhatsOnChain extends SdkWhatsOnChain {
       const response = await this.httpClient.request<WhatsOnChainTxsStatusData[]>(url, requestOptions)
 
       if (!response.data || !response.ok || response.status !== 200)
-        throw new sdk.WERR_INVALID_OPERATION(`Unable to get status for txids at this timei.`)
+        throw new WERR_INVALID_OPERATION(`Unable to get status for txids at this timei.`)
 
       const data = response.data
       for (const txid of txids) {
@@ -70,7 +82,7 @@ export class WhatsOnChain extends SdkWhatsOnChain {
       }
       r.status = 'success'
     } catch (eu: unknown) {
-      const e = sdk.WalletError.fromUnknown(eu)
+      const e = WalletError.fromUnknown(eu)
       r.error = e
     }
 
@@ -92,7 +104,7 @@ export class WhatsOnChain extends SdkWhatsOnChain {
 
     // response.statusText is often, but not always 'OK' on success...
     if (!response.data || !response.ok || response.status !== 200)
-      throw new sdk.WERR_INVALID_PARAMETER('txid', `valid transaction. '${txid}' response ${response.statusText}`)
+      throw new WERR_INVALID_PARAMETER('txid', `valid transaction. '${txid}' response ${response.statusText}`)
 
     return 0
   }
@@ -124,21 +136,21 @@ export class WhatsOnChain extends SdkWhatsOnChain {
 
       // response.statusText is often, but not always 'OK' on success...
       if (!response.data || !response.ok || response.status !== 200)
-        throw new sdk.WERR_INVALID_PARAMETER('txid', `valid transaction. '${txid}' response ${response.statusText}`)
+        throw new WERR_INVALID_PARAMETER('txid', `valid transaction. '${txid}' response ${response.statusText}`)
 
       return response.data
     }
-    throw new sdk.WERR_INTERNAL()
+    throw new WERR_INTERNAL()
   }
 
-  async getRawTxResult(txid: string): Promise<sdk.GetRawTxResult> {
-    const r: sdk.GetRawTxResult = { name: 'WoC', txid: asString(txid) }
+  async getRawTxResult(txid: string): Promise<GetRawTxResult> {
+    const r: GetRawTxResult = { name: 'WoC', txid: asString(txid) }
 
     try {
       const rawTxHex = await this.getRawTx(txid)
       if (rawTxHex) r.rawTx = asArray(rawTxHex)
     } catch (err: unknown) {
-      r.error = sdk.WalletError.fromUnknown(err)
+      r.error = WalletError.fromUnknown(err)
     }
 
     return r
@@ -153,8 +165,8 @@ export class WhatsOnChain extends SdkWhatsOnChain {
    * @param txids
    * @returns
    */
-  async postBeef(beef: Beef, txids: string[]): Promise<sdk.PostBeefResult> {
-    const r: sdk.PostBeefResult = {
+  async postBeef(beef: Beef, txids: string[]): Promise<PostBeefResult> {
+    const r: PostBeefResult = {
       name: 'WoC',
       status: 'success',
       txidResults: [],
@@ -197,10 +209,10 @@ export class WhatsOnChain extends SdkWhatsOnChain {
    * @param rawTx raw transaction to broadcast as hex string
    * @returns txid returned by transaction processor of transaction broadcast
    */
-  async postRawTx(rawTx: HexString): Promise<sdk.PostTxResultForTxid> {
+  async postRawTx(rawTx: HexString): Promise<PostTxResultForTxid> {
     let txid = Utils.toHex(doubleSha256BE(Utils.toArray(rawTx, 'hex')))
 
-    const r: sdk.PostTxResultForTxid = {
+    const r: PostTxResultForTxid = {
       txid,
       status: 'success',
       notes: []
@@ -272,7 +284,7 @@ export class WhatsOnChain extends SdkWhatsOnChain {
         }
       } catch (eu: unknown) {
         r.status = 'error'
-        const e = sdk.WalletError.fromUnknown(eu)
+        const e = WalletError.fromUnknown(eu)
         r.notes!.push({
           ...nne(),
           what: 'postRawTxCatch',
@@ -294,115 +306,7 @@ export class WhatsOnChain extends SdkWhatsOnChain {
     return r
   }
 
-  /**
-   * @param txid
-   * @returns
-   */
-  async getMerklePath(txid: string, services: sdk.WalletServices): Promise<sdk.GetMerklePathResult> {
-    const r: sdk.GetMerklePathResult = { name: 'WoCTsc', notes: [] }
-
-    const headers = this.getHttpHeaders()
-    const requestOptions = {
-      method: 'GET',
-      headers
-    }
-
-    for (let retry = 0; retry < 2; retry++) {
-      try {
-        const response = await this.httpClient.request<WhatsOnChainTscProof | WhatsOnChainTscProof[]>(
-          `${this.URL}/tx/${txid}/proof/tsc`,
-          requestOptions
-        )
-        if (response.statusText === 'Too Many Requests' && retry < 2) {
-          r.notes!.push({
-            what: 'getMerklePathRetry',
-            name: r.name,
-            status: response.status,
-            statusText: response.statusText
-          })
-          await wait(2000)
-          continue
-        }
-
-        if (response.status === 404 && response.statusText === 'Not Found') {
-          r.notes!.push({
-            what: 'getMerklePathNotFound',
-            name: r.name,
-            status: response.status,
-            statusText: response.statusText
-          })
-          return r
-        }
-
-        // response.statusText is often, but not always 'OK' on success...
-        if (!response.ok || response.status !== 200) {
-          r.notes!.push({
-            what: 'getMerklePathBadStatus',
-            name: r.name,
-            status: response.status,
-            statusText: response.statusText
-          })
-          throw new sdk.WERR_INVALID_PARAMETER('txid', `valid transaction. '${txid}' response ${response.statusText}`)
-        }
-
-        if (!response.data) {
-          // Unmined, proof not yet available.
-          r.notes!.push({
-            what: 'getMerklePathNoData',
-            name: r.name,
-            status: response.status,
-            statusText: response.statusText
-          })
-          return r
-        }
-
-        if (!Array.isArray(response.data)) response.data = [response.data]
-
-        if (response.data.length != 1) return r
-
-        const p = response.data[0]
-        const header = await services.hashToHeader(p.target)
-        if (header) {
-          const proof = {
-            index: p.index,
-            nodes: p.nodes,
-            height: header.height
-          }
-          r.merklePath = convertProofToMerklePath(txid, proof)
-          r.header = header
-          r.notes!.push({
-            what: 'getMerklePathSuccess',
-            name: r.name,
-            status: response.status,
-            statusText: response.statusText
-          })
-        } else {
-          r.notes!.push({
-            what: 'getMerklePathNoHeader',
-            target: p.target,
-            name: r.name,
-            status: response.status,
-            statusText: response.statusText
-          })
-          throw new sdk.WERR_INVALID_PARAMETER('blockhash', 'a valid on-chain block hash')
-        }
-      } catch (eu: unknown) {
-        const e = sdk.WalletError.fromUnknown(eu)
-        r.notes!.push({
-          what: 'getMerklePathError',
-          name: r.name,
-          code: e.code,
-          description: e.description
-        })
-        r.error = e
-      }
-      return r
-    }
-    r.notes!.push({ what: 'getMerklePathInternal', name: r.name })
-    throw new sdk.WERR_INTERNAL()
-  }
-
-  async updateBsvExchangeRate(rate?: sdk.BsvExchangeRate, updateMsecs?: number): Promise<sdk.BsvExchangeRate> {
+  async updateBsvExchangeRate(rate?: BsvExchangeRate, updateMsecs?: number): Promise<BsvExchangeRate> {
     if (rate) {
       // Check if the rate we know is stale enough to update.
       updateMsecs ||= 1000 * 60 * 15
@@ -427,12 +331,12 @@ export class WhatsOnChain extends SdkWhatsOnChain {
 
       // response.statusText is often, but not always 'OK' on success...
       if (!response.data || !response.ok || response.status !== 200)
-        throw new sdk.WERR_INVALID_OPERATION(`WoC exchangerate response ${response.statusText}`)
+        throw new WERR_INVALID_OPERATION(`WoC exchangerate response ${response.statusText}`)
 
       const wocrate = response.data
       if (wocrate.currency !== 'USD') wocrate.rate = NaN
 
-      const newRate: sdk.BsvExchangeRate = {
+      const newRate: BsvExchangeRate = {
         timestamp: new Date(),
         base: 'USD',
         rate: wocrate.rate
@@ -440,18 +344,18 @@ export class WhatsOnChain extends SdkWhatsOnChain {
 
       return newRate
     }
-    throw new sdk.WERR_INTERNAL()
+    throw new WERR_INTERNAL()
   }
 
   async getUtxoStatus(
     output: string,
-    outputFormat?: sdk.GetUtxoStatusOutputFormat,
+    outputFormat?: GetUtxoStatusOutputFormat,
     outpoint?: string
-  ): Promise<sdk.GetUtxoStatusResult> {
-    const r: sdk.GetUtxoStatusResult = {
+  ): Promise<GetUtxoStatusResult> {
+    const r: GetUtxoStatusResult = {
       name: 'WoC',
       status: 'error',
-      error: new sdk.WERR_INTERNAL(),
+      error: new WERR_INTERNAL(),
       details: []
     }
 
@@ -477,12 +381,12 @@ export class WhatsOnChain extends SdkWhatsOnChain {
 
         // response.statusText is often, but not always 'OK' on success...
         if (!response.data || !response.ok || response.status !== 200)
-          throw new sdk.WERR_INVALID_OPERATION(`WoC getUtxoStatus response ${response.statusText}`)
+          throw new WERR_INVALID_OPERATION(`WoC getUtxoStatus response ${response.statusText}`)
 
         const data = response.data
 
         if (data.script !== scriptHash || !Array.isArray(data.result)) {
-          throw new sdk.WERR_INTERNAL('data. is not an array')
+          throw new WERR_INTERNAL('data. is not an array')
         }
 
         if (data.result.length === 0) {
@@ -508,19 +412,17 @@ export class WhatsOnChain extends SdkWhatsOnChain {
 
         return r
       } catch (eu: unknown) {
-        const e = sdk.WalletError.fromUnknown(eu)
+        const e = WalletError.fromUnknown(eu)
         if (e.code !== 'ECONNRESET' || retry > 2) {
-          r.error = new sdk.WERR_INTERNAL(
-            `service failure: ${url}, error: ${JSON.stringify(sdk.WalletError.fromUnknown(eu))}`
-          )
+          r.error = new WERR_INTERNAL(`service failure: ${url}, error: ${JSON.stringify(WalletError.fromUnknown(eu))}`)
           return r
         }
       }
     }
   }
 
-  async getScriptHashConfirmedHistory(hash: string): Promise<sdk.GetScriptHashHistoryResult> {
-    const r: sdk.GetScriptHashHistoryResult = {
+  async getScriptHashConfirmedHistory(hash: string): Promise<GetScriptHashHistoryResult> {
+    const r: GetScriptHashHistoryResult = {
       name: 'WoC',
       status: 'error',
       error: undefined,
@@ -553,14 +455,14 @@ export class WhatsOnChain extends SdkWhatsOnChain {
 
         // response.statusText is often, but not always 'OK' on success...
         if (!response.data || !response.ok || response.status !== 200) {
-          r.error = new sdk.WERR_BAD_REQUEST(
+          r.error = new WERR_BAD_REQUEST(
             `WoC getScriptHashConfirmedHistory response ${response.ok} ${response.status} ${response.statusText}`
           )
           return r
         }
 
         if (response.data.error) {
-          r.error = new sdk.WERR_BAD_REQUEST(`WoC getScriptHashConfirmedHistory error ${response.data.error}`)
+          r.error = new WERR_BAD_REQUEST(`WoC getScriptHashConfirmedHistory error ${response.data.error}`)
           return r
         }
 
@@ -569,10 +471,10 @@ export class WhatsOnChain extends SdkWhatsOnChain {
 
         return r
       } catch (eu: unknown) {
-        const e = sdk.WalletError.fromUnknown(eu)
+        const e = WalletError.fromUnknown(eu)
         if (e.code !== 'ECONNRESET' || retry > 2) {
-          r.error = new sdk.WERR_INTERNAL(
-            `WoC getScriptHashConfirmedHistory service failure: ${url}, error: ${JSON.stringify(sdk.WalletError.fromUnknown(eu))}`
+          r.error = new WERR_INTERNAL(
+            `WoC getScriptHashConfirmedHistory service failure: ${url}, error: ${JSON.stringify(WalletError.fromUnknown(eu))}`
           )
           return r
         }
@@ -582,8 +484,8 @@ export class WhatsOnChain extends SdkWhatsOnChain {
     return r
   }
 
-  async getScriptHashUnconfirmedHistory(hash: string): Promise<sdk.GetScriptHashHistoryResult> {
-    const r: sdk.GetScriptHashHistoryResult = {
+  async getScriptHashUnconfirmedHistory(hash: string): Promise<GetScriptHashHistoryResult> {
+    const r: GetScriptHashHistoryResult = {
       name: 'WoC',
       status: 'error',
       error: undefined,
@@ -616,14 +518,14 @@ export class WhatsOnChain extends SdkWhatsOnChain {
 
         // response.statusText is often, but not always 'OK' on success...
         if (!response.data || !response.ok || response.status !== 200) {
-          r.error = new sdk.WERR_BAD_REQUEST(
+          r.error = new WERR_BAD_REQUEST(
             `WoC getScriptHashUnconfirmedHistory response ${response.ok} ${response.status} ${response.statusText}`
           )
           return r
         }
 
         if (response.data.error) {
-          r.error = new sdk.WERR_BAD_REQUEST(`WoC getScriptHashUnconfirmedHistory error ${response.data.error}`)
+          r.error = new WERR_BAD_REQUEST(`WoC getScriptHashUnconfirmedHistory error ${response.data.error}`)
           return r
         }
 
@@ -632,10 +534,10 @@ export class WhatsOnChain extends SdkWhatsOnChain {
 
         return r
       } catch (eu: unknown) {
-        const e = sdk.WalletError.fromUnknown(eu)
+        const e = WalletError.fromUnknown(eu)
         if (e.code !== 'ECONNRESET' || retry > 2) {
-          r.error = new sdk.WERR_INTERNAL(
-            `WoC getScriptHashUnconfirmedHistory service failure: ${url}, error: ${JSON.stringify(sdk.WalletError.fromUnknown(eu))}`
+          r.error = new WERR_INTERNAL(
+            `WoC getScriptHashUnconfirmedHistory service failure: ${url}, error: ${JSON.stringify(WalletError.fromUnknown(eu))}`
           )
           return r
         }
@@ -645,7 +547,7 @@ export class WhatsOnChain extends SdkWhatsOnChain {
     return r
   }
 
-  async getScriptHashHistory(hash: string): Promise<sdk.GetScriptHashHistoryResult> {
+  async getScriptHashHistory(hash: string): Promise<GetScriptHashHistoryResult> {
     const r1 = await this.getScriptHashConfirmedHistory(hash)
     if (r1.error || r1.status !== 'success') return r1
     const r2 = await this.getScriptHashUnconfirmedHistory(hash)
@@ -653,6 +555,201 @@ export class WhatsOnChain extends SdkWhatsOnChain {
     r1.history = r1.history.concat(r2.history)
     return r1
   }
+
+  /**
+    {
+      "hash": "000000000000000004a288072ebb35e37233f419918f9783d499979cb6ac33eb",
+      "confirmations": 328433,
+      "size": 14421,
+      "height": 575045,
+      "version": 536928256,
+      "versionHex": "2000e000",
+      "merkleroot": "4ebcba09addd720991d03473f39dce4b9a72cc164e505cd446687a54df9b1585",
+      "time": 1553416668,
+      "mediantime": 1553414858,
+      "nonce": 87914848,
+      "bits": "180997ee",
+      "difficulty": 114608607557.4425,
+      "chainwork": "000000000000000000000000000000000000000000ddf5d385546872bab7dc01",
+      "previousblockhash": "00000000000000000988156c7075dc9147a5b62922f1310862e8b9000d46dd9b",
+      "nextblockhash": "00000000000000000112b36a37c10235fa0c991f680bc5482ba9692e0ae697db",
+      "nTx": 0,
+      "num_tx": 5
+    }
+   */
+  async getBlockHeaderByHash(hash: string): Promise<BlockHeader | undefined> {
+    const headers = this.getHttpHeaders()
+    const requestOptions = {
+      method: 'GET',
+      headers
+    }
+
+    const url = `${this.URL}/block/${hash}/header`
+
+    for (let retry = 0; retry < 2; retry++) {
+      const response = await this.httpClient.request<WocHeader>(url, requestOptions)
+      if (response.statusText === 'Too Many Requests' && retry < 2) {
+        await wait(2000)
+        continue
+      }
+
+      if (response.status === 404 && response.statusText === 'Not Found') return undefined
+
+      // response.statusText is often, but not always 'OK' on success...
+      if (!response.data || !response.ok || response.status !== 200)
+        throw new WERR_INVALID_PARAMETER('hash', `valid block hash. '${hash}' response ${response.statusText}`)
+
+      const header = convertWocToBlockHeaderHex(response.data)
+
+      return header
+    }
+    throw new WERR_INTERNAL()
+  }
+
+  async getChainInfo(): Promise<WocChainInfo> {
+    const headers = this.getHttpHeaders()
+    const requestOptions = {
+      method: 'GET',
+      headers
+    }
+
+    const url = `${this.URL}/chain/info`
+
+    for (let retry = 0; retry < 2; retry++) {
+      const response = await this.httpClient.request<WocChainInfo>(url, requestOptions)
+      if (response.statusText === 'Too Many Requests' && retry < 2) {
+        await wait(2000)
+        continue
+      }
+
+      // response.statusText is often, but not always 'OK' on success...
+      if (!response.data || !response.ok || response.status !== 200)
+        throw new WERR_INVALID_PARAMETER('hash', `valid block hash. '${url}' response ${response.statusText}`)
+
+      return response.data
+    }
+    throw new WERR_INTERNAL()
+  }
+}
+
+/**
+ *
+ */
+export class WhatsOnChain extends WhatsOnChainNoServices {
+  services: Services
+
+  constructor(chain: Chain = 'main', config: WhatsOnChainConfig = {}, services?: Services) {
+    super(chain, config)
+    this.services = services || new Services(chain)
+  }
+
+  /**
+   * @param txid
+   * @returns
+   */
+  async getMerklePath(txid: string, services: WalletServices): Promise<GetMerklePathResult> {
+    const r: GetMerklePathResult = { name: 'WoCTsc', notes: [] }
+
+    const headers = this.getHttpHeaders()
+    const requestOptions = {
+      method: 'GET',
+      headers
+    }
+
+    for (let retry = 0; retry < 2; retry++) {
+      try {
+        const response = await this.httpClient.request<WhatsOnChainTscProof | WhatsOnChainTscProof[]>(
+          `${this.URL}/tx/${txid}/proof/tsc`,
+          requestOptions
+        )
+        if (response.statusText === 'Too Many Requests' && retry < 2) {
+          r.notes!.push({
+            what: 'getMerklePathRetry',
+            name: r.name,
+            status: response.status,
+            statusText: response.statusText
+          })
+          await wait(2000)
+          continue
+        }
+
+        if (response.status === 404 && response.statusText === 'Not Found') {
+          r.notes!.push({
+            what: 'getMerklePathNotFound',
+            name: r.name,
+            status: response.status,
+            statusText: response.statusText
+          })
+          return r
+        }
+
+        // response.statusText is often, but not always 'OK' on success...
+        if (!response.ok || response.status !== 200) {
+          r.notes!.push({
+            what: 'getMerklePathBadStatus',
+            name: r.name,
+            status: response.status,
+            statusText: response.statusText
+          })
+          throw new WERR_INVALID_PARAMETER('txid', `valid transaction. '${txid}' response ${response.statusText}`)
+        }
+
+        if (!response.data) {
+          // Unmined, proof not yet available.
+          r.notes!.push({
+            what: 'getMerklePathNoData',
+            name: r.name,
+            status: response.status,
+            statusText: response.statusText
+          })
+          return r
+        }
+
+        if (!Array.isArray(response.data)) response.data = [response.data]
+
+        if (response.data.length != 1) return r
+
+        const p = response.data[0]
+        const header = await services.hashToHeader(p.target)
+        if (header) {
+          const proof = {
+            index: p.index,
+            nodes: p.nodes,
+            height: header.height
+          }
+          r.merklePath = convertProofToMerklePath(txid, proof)
+          r.header = header
+          r.notes!.push({
+            what: 'getMerklePathSuccess',
+            name: r.name,
+            status: response.status,
+            statusText: response.statusText
+          })
+        } else {
+          r.notes!.push({
+            what: 'getMerklePathNoHeader',
+            target: p.target,
+            name: r.name,
+            status: response.status,
+            statusText: response.statusText
+          })
+          throw new WERR_INVALID_PARAMETER('blockhash', 'a valid on-chain block hash')
+        }
+      } catch (eu: unknown) {
+        const e = WalletError.fromUnknown(eu)
+        r.notes!.push({
+          what: 'getMerklePathError',
+          name: r.name,
+          code: e.code,
+          description: e.description
+        })
+        r.error = e
+      }
+      return r
+    }
+    r.notes!.push({ what: 'getMerklePathInternal', name: r.name })
+    throw new WERR_INTERNAL()
+  }
 }
 
 interface WhatsOnChainTscProof {
@@ -722,3 +819,66 @@ interface WhatsOnChainUtxoStatus {
     status: string // 'confirmed'
   }[]
 }
+
+export interface WocChainInfo {
+  chain: string // "main",
+  blocks: number // 635302,
+  headers: number // 635299,
+  bestblockhash: string // "000000000000000002a40d7410a6c08109521c14f4cf354e7b352b4eab8aa4ea",
+  difficulty: number // 287310033717.7086,
+  mediantime: number // 1589703256,
+  verificationprogress: number // 0.9999754124031851,
+  pruned: boolean // false,
+  chainwork: string // "0000000000000000000000000000000000000000010969f724913e0fe59377f4"
+}
+
+// WhatsOnChain headers looks like:
+export interface WocHeader {
+  hash: string //"00000000000000000836c9c44151acbf374c6d4a9713d43b5e95011bdbd1ff2e"
+  size: number // 71646128,
+  height: number // 760633,
+  version: number // 712441856,
+  versionHex: string // "2a770000",
+  merkleroot: string // "af80d255ca21d9ccdd2cc3576dc532adc7fcbc324ce2db3dec8d54079b56a001",
+  time: number // 1665274100,
+  mediantime: number // 1665270280,
+  nonce: number // 618555943,
+  bits: number | string // decimal of ox180dc8e5,
+  difficulty: number // 79761715531.82063,
+  chainwork: string // "0000000000000000000000000000000000000000013d02d8de0ec6cd019bb3a1",
+  previousblockhash: string // "00000000000000000272ad9db518e5eeac702f1b00ffa6dc9605f687301dda99",
+
+  confirmations: number // 3,
+  txcount: number // 45168,
+  nextblockhash: string // "000000000000000004e01d72ccb7502f0412cc12d7e50f6fafa99ac6f89fd063",
+  // coinbaseTx
+  // orphaned
+}
+
+export function convertWocToBlockHeaderHex(woc: WocHeader): BlockHeader {
+  const bits: number = typeof woc.bits === 'string' ? parseInt(woc.bits, 16) : woc.bits
+  if (!woc.previousblockhash) {
+    woc.previousblockhash = '0000000000000000000000000000000000000000000000000000000000000000' // genesis
+  }
+  return {
+    version: woc.version,
+    previousHash: woc.previousblockhash,
+    merkleRoot: woc.merkleroot,
+    time: woc.time,
+    bits,
+    nonce: woc.nonce,
+    hash: woc.hash,
+    height: woc.height
+  }
+}
+
+export async function getWhatsOnChainBlockHeaderByHash(
+  hash: string,
+  chain: Chain = 'main',
+  apiKey?: string
+): Promise<BlockHeader | undefined> {
+  const config = apiKey ? { apiKey } : {}
+  const woc = new WhatsOnChain(chain, config)
+  const header = await woc.getBlockHeaderByHash(hash)
+  return header
+}