@bopen-io/wallet-toolbox 1.7.18

package/src/services/chaintracker/BHServiceClient.ts

@@ -0,0 +1,212 @@
+import { BlockHeadersService, Utils } from '@bsv/sdk'
+import { ChaintracksServiceClient, ChaintracksServiceClientOptions } from './chaintracks/ChaintracksServiceClient'
+import { serializeBaseBlockHeader } from './chaintracks/util/blockHeaderUtilities'
+import { HeaderListener, ReorgListener, ChaintracksInfoApi } from './chaintracks/Api/ChaintracksClientApi'
+import { Chain } from '../../sdk/types'
+import { BaseBlockHeader, BlockHeader } from '../../sdk/WalletServices.interfaces'
+
+interface BHSHeader {
+  hash: string
+  version: number
+  prevBlockHash: string
+  merkleRoot: string
+  creationTimestamp: number
+  difficultyTarget: number
+  nonce: number
+  work: string
+}
+
+interface BHSHeaderState {
+  header: BHSHeader
+  state: string
+  chainWork: string
+  height: number
+}
+
+export class BHServiceClient implements ChaintracksServiceClient {
+  bhs: BlockHeadersService
+  cache: Record<number, string>
+  chain: Chain
+  serviceUrl: string
+  options: ChaintracksServiceClientOptions
+  apiKey: string
+
+  constructor(chain: Chain, url: string, apiKey: string) {
+    this.bhs = new BlockHeadersService(url, { apiKey })
+    this.cache = {}
+    this.chain = chain
+    this.serviceUrl = url
+    this.options = ChaintracksServiceClient.createChaintracksServiceClientOptions()
+    this.apiKey = apiKey
+  }
+
+  async currentHeight(): Promise<number> {
+    return await this.bhs.currentHeight()
+  }
+
+  async isValidRootForHeight(root: string, height: number): Promise<boolean> {
+    const cachedRoot = this.cache[height]
+    if (cachedRoot) {
+      return cachedRoot === root
+    }
+    const isValid = await this.bhs.isValidRootForHeight(root, height)
+    this.cache[height] = root
+    return isValid
+  }
+
+  async getPresentHeight(): Promise<number> {
+    return await this.bhs.currentHeight()
+  }
+
+  async findHeaderForHeight(height: number): Promise<BlockHeader | undefined> {
+    const response = await this.getJsonOrUndefined<BHSHeader[]>(`/api/v1/chain/header/byHeight?height=${height}`)
+    const header = response?.[0]
+    if (!header) return undefined
+    const formatted: BlockHeader = {
+      version: header.version,
+      previousHash: header.prevBlockHash,
+      merkleRoot: header.merkleRoot,
+      time: header.creationTimestamp,
+      bits: header.difficultyTarget,
+      nonce: header.nonce,
+      height,
+      hash: header.hash
+    }
+    return formatted
+  }
+
+  async findHeaderForBlockHash(hash: string): Promise<BlockHeader | undefined> {
+    const response = await this.getJsonOrUndefined<BHSHeaderState>(`/api/v1/chain/header/state/${hash}`)
+    if (!response?.header) return undefined
+    const formatted: BlockHeader = {
+      version: response.header.version,
+      previousHash: response.header.prevBlockHash,
+      merkleRoot: response.header.merkleRoot,
+      time: response.header.creationTimestamp,
+      bits: response.header.difficultyTarget,
+      nonce: response.header.nonce,
+      height: response.height,
+      hash: response.header.hash
+    }
+    return formatted
+  }
+
+  async getHeaders(height: number, count: number): Promise<string> {
+    const response = await this.getJsonOrUndefined<BHSHeader[]>(
+      `/api/v1/chain/header/byHeight?height=${height}&count=${count}`
+    )
+    if (!response) return ''
+    if (response.length < count) throw new Error('Cannot retrieve enough headers')
+    const headers = response.map(response => {
+      const header: BaseBlockHeader = {
+        version: response.version,
+        previousHash: response.prevBlockHash,
+        merkleRoot: response.merkleRoot,
+        time: response.creationTimestamp,
+        bits: response.difficultyTarget,
+        nonce: response.nonce
+      }
+      return serializeBaseBlockHeader(header)
+    })
+    return headers.reduce((str: string, arr: number[]) => str + Utils.toHex(arr), '')
+  }
+
+  async findChainWorkForBlockHash(hash: string): Promise<string | undefined> {
+    throw new Error('Not implemented')
+  }
+
+  async findChainTipHeader(): Promise<BlockHeader> {
+    const response = await this.getJson<BHSHeaderState>('/api/v1/chain/tip/longest')
+    const formatted: BlockHeader = {
+      version: response.header.version,
+      previousHash: response.header.prevBlockHash,
+      merkleRoot: response.header.merkleRoot,
+      time: response.header.creationTimestamp,
+      bits: response.header.difficultyTarget,
+      nonce: response.header.nonce,
+      height: response.height,
+      hash: response.header.hash
+    }
+    return formatted
+  }
+
+  async getJsonOrUndefined<T>(path: string): Promise<T | undefined> {
+    let e: Error | undefined = undefined
+    for (let retry = 0; retry < 3; retry++) {
+      try {
+        const r = await fetch(`${this.serviceUrl}${path}`, { headers: { Authorization: `Bearer ${this.apiKey}` } })
+        if (r.status !== 200) throw new Error(JSON.stringify(r))
+        const v = <T>await r.json()
+        if (!v) return undefined
+        return v
+      } catch (eu: unknown) {
+        e = eu as Error
+      }
+      if (e && e.name !== 'ECONNRESET') break
+    }
+    if (e) throw e
+  }
+
+  async getJson<T>(path: string): Promise<T> {
+    const r = await this.getJsonOrUndefined<T>(path)
+    if (r === undefined) throw new Error('Value was undefined. Requested object may not exist.')
+    return r
+  }
+
+  /*
+    Please note that all methods hereafter are included only to match the interface of ChaintracksServiceClient.
+  */
+
+  async postJsonVoid<T>(path: string, params: T): Promise<void> {
+    throw new Error('Not implemented')
+  }
+
+  async addHeader(header: any): Promise<void> {
+    throw new Error('Not implemented')
+  }
+
+  async findHeaderForMerkleRoot(merkleRoot: string, height?: number): Promise<undefined> {
+    throw new Error('Not implemented')
+  }
+
+  async startListening(): Promise<void> {
+    throw new Error('Not implemented')
+  }
+
+  async listening(): Promise<void> {
+    throw new Error('Not implemented')
+  }
+
+  async isSynchronized(): Promise<boolean> {
+    throw new Error('Not implemented')
+  }
+
+  async getChain(): Promise<Chain> {
+    return this.chain
+  }
+
+  async isListening(): Promise<boolean> {
+    throw new Error('Not implemented')
+  }
+
+  async getChainTipHeader(): Promise<BlockHeader> {
+    throw new Error('Not implemented')
+  }
+
+  async findChainTipHash(): Promise<string> {
+    throw new Error('Not implemented')
+  }
+
+  async subscribeHeaders(listener: HeaderListener): Promise<string> {
+    throw new Error('Method not implemented.')
+  }
+  async subscribeReorgs(listener: ReorgListener): Promise<string> {
+    throw new Error('Method not implemented.')
+  }
+  async unsubscribe(subscriptionId: string): Promise<boolean> {
+    throw new Error('Method not implemented.')
+  }
+  async getInfo(): Promise<ChaintracksInfoApi> {
+    throw new Error('Method not implemented.')
+  }
+}

package/src/services/chaintracker/ChaintracksChainTracker.ts

@@ -0,0 +1,71 @@
+import { ChainTracker } from '@bsv/sdk'
+import { ChaintracksServiceClient } from './chaintracks/ChaintracksServiceClient'
+import { Chain } from '../../sdk/types'
+import { WalletError } from '../../sdk/WalletError'
+import { wait } from '../../utility/utilityHelpers'
+import { WERR_INTERNAL } from '../../sdk/WERR_errors'
+import { BlockHeader } from '../../sdk/WalletServices.interfaces'
+import { ChaintracksClientApi } from './chaintracks/Api/ChaintracksClientApi'
+
+export interface ChaintracksChainTrackerOptions {
+  maxRetries?: number
+}
+
+export class ChaintracksChainTracker implements ChainTracker {
+  chaintracks: ChaintracksClientApi
+  cache: Record<number, string>
+  options: ChaintracksChainTrackerOptions
+
+  constructor(chain?: Chain, chaintracks?: ChaintracksClientApi, options?: ChaintracksChainTrackerOptions) {
+    chain ||= 'main'
+    this.chaintracks =
+      chaintracks ?? new ChaintracksServiceClient(chain, `https://${chain}net-chaintracks.babbage.systems`)
+    this.cache = {}
+    this.options = options || {}
+  }
+
+  async currentHeight(): Promise<number> {
+    return await this.chaintracks.getPresentHeight()
+  }
+
+  async isValidRootForHeight(root: string, height: number): Promise<boolean> {
+    const cachedRoot = this.cache[height]
+    if (cachedRoot) {
+      return cachedRoot === root
+    }
+
+    let header: BlockHeader | undefined
+
+    const retries = this.options.maxRetries || 3
+
+    let error: WalletError | undefined = undefined
+
+    for (let tryCount = 1; tryCount <= retries; tryCount++) {
+      try {
+        header = await this.chaintracks.findHeaderForHeight(height)
+
+        if (!header) {
+          return false
+        }
+
+        break
+      } catch (eu: unknown) {
+        error = WalletError.fromUnknown(eu)
+        if (tryCount > retries) {
+          throw error
+        }
+        await wait(1000)
+      }
+    }
+
+    if (!header) throw new WERR_INTERNAL('no header should have returned false or thrown an error.')
+
+    this.cache[height] = header.merkleRoot
+
+    if (header.merkleRoot !== root) {
+      return false
+    }
+
+    return true
+  }
+}

package/src/services/chaintracker/__tests/ChaintracksChainTracker.test.ts

@@ -0,0 +1,33 @@
+import { ChaintracksChainTracker } from '../index.all'
+import { sdk } from '../../../index.client'
+
+const includeTestChaintracks = false
+
+describe('ChaintracksChaintracker tests', () => {
+  jest.setTimeout(99999999)
+
+  test(`0 test`, async () => {
+    if (!includeTestChaintracks) return
+    await testChaintracksChaintracker('test')
+  })
+
+  test(`1 main`, async () => {
+    await testChaintracksChaintracker('main')
+  })
+})
+
+async function testChaintracksChaintracker(chain: sdk.Chain) {
+  const tracker = new ChaintracksChainTracker(chain)
+  const height = await tracker.currentHeight()
+  expect(height).toBeGreaterThan(877598)
+  const okMain = await tracker.isValidRootForHeight(
+    '2bf2edb5fa42aa773c6c13bc90e097b4e7de7ca1df2227f433be75ceace339e9',
+    877599
+  )
+  expect(okMain).toBe(chain === 'main')
+  const okTest = await tracker.isValidRootForHeight(
+    '5513f13554442588dd9acf395072bf1d2e7d5d360fbc42d3ab1fa2026b17c200',
+    1654265
+  )
+  expect(okTest).toBe(chain === 'test')
+}

package/src/services/chaintracker/__tests/ChaintracksServiceClient.test.ts

@@ -0,0 +1,29 @@
+import { sdk } from '../../../index.client'
+import { ChaintracksServiceClient } from '../chaintracks/index.client'
+
+const includeTestChaintracks = false
+
+describe('ChaintracksServiceClient tests', () => {
+  jest.setTimeout(99999999)
+
+  test('0 mainNet findHeaderForHeight', async () => {
+    const client = makeClient('main')
+    const r = await client.findHeaderForHeight(877595)
+    expect(r?.hash).toBe('00000000000000000b010edee7422c59ec9131742e35f3e0d5837d710b961406')
+    expect(await client.findHeaderForHeight(999999999)).toBe(undefined)
+  })
+
+  test('1 testNet findHeaderForHeight', async () => {
+    if (!includeTestChaintracks) return
+    const client = makeClient('test')
+    const r = await client.findHeaderForHeight(1651723)
+    expect(r?.hash).toBe('0000000049686fe721f70614c89df146e410240f838b8f3ef8e6471c6dfdd153')
+    expect(await client.findHeaderForHeight(999999999)).toBe(undefined)
+  })
+})
+
+function makeClient(chain: sdk.Chain) {
+  //const chaintracksUrl = `https://npm-registry.babbage.systems:${chain === 'main' ? 8084 : 8083}`
+  const chaintracksUrl = `https://${chain}net-chaintracks.babbage.systems`
+  return new ChaintracksServiceClient(chain, chaintracksUrl)
+}

package/src/services/chaintracker/chaintracks/Api/BlockHeaderApi.ts

@@ -0,0 +1,72 @@
+import { BaseBlockHeader, BlockHeader } from '../../../../sdk/WalletServices.interfaces'
+
+export { BaseBlockHeader, BlockHeader } from '../../../../sdk/WalletServices.interfaces'
+
+/**
+ * The "live" portion of the block chain is recent history that can conceivably be subject to reorganizations.
+ * The additional fields support tracking orphan blocks, chain forks, and chain reorgs.
+ */
+export interface LiveBlockHeader extends BlockHeader {
+  /**
+   * The cummulative chainwork achieved by the addition of this block to the chain.
+   * Chainwork only matters in selecting the active chain.
+   */
+  chainWork: string
+  /**
+   * True only if this header is currently a chain tip. e.g. There is no header that follows it by previousHash or previousHeaderId.
+   */
+  isChainTip: boolean
+  /**
+   * True only if this header is currently on the active chain.
+   */
+  isActive: boolean
+  /**
+   * As there may be more than one header with identical height values due to orphan tracking,
+   * headers are assigned a unique headerId while part of the "live" portion of the block chain.
+   */
+  headerId: number
+  /**
+   * Every header in the "live" portion of the block chain is linked to an ancestor header through
+   * both its previousHash and previousHeaderId properties.
+   *
+   * Due to forks, there may be multiple headers with identical `previousHash` and `previousHeaderId` values.
+   * Of these, only one (the header on the active chain) will have `isActive` === true.
+   */
+  previousHeaderId: number | null
+}
+
+//
+// TYPE GUARDS
+//
+
+/**
+ * Type guard function.
+ * @publicbody
+ */
+export function isLive(header: BlockHeader | LiveBlockHeader): header is LiveBlockHeader {
+  return (header as LiveBlockHeader).headerId !== undefined
+}
+
+/**
+ * Type guard function.
+ * @publicbody
+ */
+export function isBaseBlockHeader(header: BaseBlockHeader | BlockHeader | LiveBlockHeader): header is BaseBlockHeader {
+  return typeof header.previousHash === 'string'
+}
+
+/**
+ * Type guard function.
+ * @publicbody
+ */
+export function isBlockHeader(header: BaseBlockHeader | BlockHeader | LiveBlockHeader): header is LiveBlockHeader {
+  return 'height' in header && typeof header.previousHash === 'string'
+}
+
+/**
+ * Type guard function.
+ * @publicbody
+ */
+export function isLiveBlockHeader(header: BaseBlockHeader | BlockHeader | LiveBlockHeader): header is LiveBlockHeader {
+  return 'chainwork' in header && typeof header.previousHash === 'string'
+}

package/src/services/chaintracker/chaintracks/Api/BulkIngestorApi.ts

@@ -0,0 +1,83 @@
+import { Chain } from '../../../../sdk/types'
+import { HeightRange, HeightRanges } from '../util/HeightRange'
+import { BlockHeader } from './BlockHeaderApi'
+import { ChaintracksStorageApi } from './ChaintracksStorageApi'
+
+export interface BulkIngestorBaseOptions {
+  /**
+   * The target chain: "main" or "test"
+   */
+  chain: Chain
+
+  /**
+   * Required.
+   *
+   * The name of the JSON resource to request from CDN which describes currently
+   * available bulk block header resources.
+   */
+  jsonResource: string | undefined
+}
+
+export interface BulkIngestorApi {
+  /**
+   * Close and release all resources.
+   */
+  shutdown(): Promise<void>
+
+  /**
+   * If the bulk ingestor is capable, return the approximate
+   * present height of the actual chain being tracked.
+   * Otherwise, return undefined.
+   *
+   * May not assume that setStorage has been called.
+   */
+  getPresentHeight(): Promise<number | undefined>
+
+  /**
+   * A BulkIngestor fetches and updates storage with bulk headers in bulkRange.
+   *
+   * If it can, it must also fetch live headers in fetch range that are not in bulkRange and return them as an array.
+   *
+   * The storage methods `insertBulkFile`, `updateBulkFile`, and `addBulkHeaders` should be used to add bulk headers to storage.
+   *
+   * @param before bulk and live range of headers before ingesting any new headers.
+   * @param fetchRange range of headers still needed, includes both missing bulk and live headers.
+   * @param bulkRange range of bulk headers still needed
+   * @param priorLiveHeaders any headers accumulated by prior bulk ingestor(s) that are too recent for bulk storage.
+   * @returns new live headers: headers in fetchRange but not in bulkRange
+   */
+  fetchHeaders(
+    before: HeightRanges,
+    fetchRange: HeightRange,
+    bulkRange: HeightRange,
+    priorLiveHeaders: BlockHeader[]
+  ): Promise<BlockHeader[]>
+
+  /**
+   * A BulkIngestor has two potential goals:
+   * 1. To source missing bulk headers and include them in bulk storage.
+   * 2. To source missing live headers to be forwarded to live storage.
+   *
+   * @param presentHeight current height of the active chain tip, may lag the true value.
+   * @param before current bulk and live storage height ranges, either may be empty.
+   * @param priorLiveHeaders any headers accumulated by prior bulk ingestor(s) that are too recent for bulk storage.
+   * @returns updated priorLiveHeaders including any accumulated by this ingestor
+   */
+  synchronize(presentHeight: number, before: HeightRanges, priorLiveHeaders: BlockHeader[]): Promise<BulkSyncResult>
+
+  /**
+   * Called before first Synchronize with reference to storage.
+   * Components requiring asynchronous setup can override base class implementation.
+   * @param storage
+   */
+  setStorage(storage: ChaintracksStorageApi, log: (...args: any[]) => void): Promise<void>
+
+  storage(): ChaintracksStorageApi
+}
+
+export interface BulkSyncResult {
+  liveHeaders: BlockHeader[]
+  liveRange: HeightRange
+  done: boolean
+  log: string
+}

package/src/services/chaintracker/chaintracks/Api/BulkStorageApi.ts

@@ -0,0 +1,92 @@
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import { Chain } from '../../../../sdk/types'
+import { BlockHeader, LiveBlockHeader } from './BlockHeaderApi'
+import { HeightRange } from '../util/HeightRange'
+import { ChaintracksStorageApi } from './ChaintracksStorageApi'
+import { ChaintracksFsApi } from './ChaintracksFsApi'
+
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
+export interface BulkStorageBaseOptions {
+  /**
+   * The target chain: "main" or "test"
+   */
+  chain: Chain
+  fs: ChaintracksFsApi
+}
+
+/**
+ * Handles block header storage and retrieval older than the "live" portion of the chain.
+ * Height is the primary and only indexing field required.
+ * Only stores headers on the active chain; no orphans, no forks, no reorgs.
+ */
+export interface BulkStorageApi {
+  /**
+   * Close and release all resources.
+   */
+  shutdown(): Promise<void>
+
+  /**
+   * @returns the height of the most recent header in bulk storage or -1 if empty.
+   */
+  getMaxHeight(): Promise<number>
+
+  /**
+   * @returns available bulk block header height range: `(0, getMaxHeight())`
+   */
+  getHeightRange(): Promise<HeightRange>
+
+  /**
+   * Append new Block Headers to BulkStorage.
+   * Requires that these headers directly extend existing headers.
+   * maxHeight of existing plus one equals minHeight of `headers`.
+   * hash of last existing equals previousHash of first in `headers`.
+   * Checks that all `headers` are valid (hash, previousHash)
+   *
+   * Duplicate headers must be ignored.
+   *
+   * @param minHeight must match height of first header in buffer
+   * @param count times 80 must equal headers.length
+   * @param headers encoded as packed array of 80 byte serialized block headers
+   */
+  appendHeaders(minHeight: number, count: number, headers: Uint8Array): Promise<void>
+
+  /**
+   * Returns block header for a given block height on active chain.
+   * @param hash block hash
+   */
+  findHeaderForHeightOrUndefined(height: number): Promise<BlockHeader | undefined>
+
+  /**
+   * Returns block header for a given block height on active chain.
+   * Throws if not found.
+   * @param hash block hash
+   */
+  findHeaderForHeight(height: number): Promise<BlockHeader>
+
+  /**
+   * Adds headers in 80 byte serialized format to a buffer.
+   * Only adds active headers.
+   * returned array length divided by 80 is the actual number returned.
+   *
+   * Returns the buffer.
+   *
+   * @param height of first header
+   * @param count of headers
+   */
+  headersToBuffer(height: number, count: number): Promise<Uint8Array>
+
+  /**
+   * Exports current bulk headers, including all ingests, excluding live headers to static header files.
+   * @param rootFolder Where the json and headers files will be written
+   * @param jsonFilename The name of the json file.
+   * @param maxPerFile The maximum headers per file.
+   */
+  exportBulkHeaders(rootFolder: string, jsonFilename: string, maxPerFile: number): Promise<void>
+
+  /**
+   * Called before first Synchronize with reference to storage.
+   * Components requiring asynchronous setup can override base class implementation.
+   * @param storage
+   */
+  setStorage(storage: ChaintracksStorageApi, log: (...args: any[]) => void): Promise<void>
+}

package/src/services/chaintracker/chaintracks/Api/ChaintracksApi.ts

@@ -0,0 +1,64 @@
+import { Chain } from '../../../../sdk/types'
+import { BulkIngestorApi } from './BulkIngestorApi'
+import { ChaintracksApi } from './ChaintracksClientApi'
+import { LiveIngestorApi } from './LiveIngestorApi'
+import { ChaintracksFsApi } from './ChaintracksFsApi'
+import { ChaintracksStorageApi } from './ChaintracksStorageApi'
+
+export interface ChaintracksOptions {
+  chain: Chain
+  storage?: ChaintracksStorageApi
+  bulkIngestors: BulkIngestorApi[]
+  liveIngestors: LiveIngestorApi[]
+
+  /**
+   * Maximum number of missing headers to pursue when listening for new headers.
+   * Normally, large numbers of missing headers are handled by bulk ingestors.
+   */
+  addLiveRecursionLimit: number
+  /**
+   * Optional logging method
+   */
+  logging?: (...args: any[]) => void
+  /**
+   * If true, this chaintracks instance will only service read requests for existing data.
+   * Shared storage only requires one readonly false instance to manage and update storage.
+   */
+  readonly: boolean
+}
+
+export interface ChaintracksManagementApi extends ChaintracksApi {
+  /**
+   * close and release all resources
+   */
+  destroy(): Promise<void>
+
+  /**
+   * Verifies that all headers from the tip back to genesis can be retrieved, in order,
+   * by height, and that they obey previousHash constraint.
+   *
+   * Additional validations may be addeded.
+   *
+   * This is a slow operation.
+   */
+  validate(): Promise<boolean>
+
+  /**
+   * Exports current bulk headers, including all ingests, excluding live headers to static header files.
+   *
+   * Useful for bulk ingestors such as those derived from BulkIngestorCDN.
+   *
+   * @param toFolder Where the json and headers files will be written
+   * @param toFs The ChaintracksFsApi to use for writing files. If not provided, the default file system will be used.
+   * @param sourceUrl Optional source URL to include in the exported files. Set if exported files will be transferred to a CDN.
+   * @param toHeadersPerFile The maximum headers per file. Default is 100,000 (8MB)
+   * @param maxHeight The maximum height to export. Default is the current bulk storage max height.
+   */
+  exportBulkHeaders(
+    toFolder: string,
+    toFs: ChaintracksFsApi,
+    sourceUrl?: string,
+    toHeadersPerFile?: number,
+    maxHeight?: number
+  ): Promise<void>
+}