@bsv/wallet-toolbox 1.5.21 → 1.6.1

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

@@ -0,0 +1,89 @@
+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
+
+  /**
+   * If true, and the bulk ingestor supports it, bypass the live database
+   * up to `liveHeightThreshold` of available headers remaining.
+   */
+  bypassLiveEnabled: boolean
+}
+
+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): 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): 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
+  /**
+   * Event logging level
+   */
+  logging: undefined | 'all'
+  /**
+   * 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>
+}

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

@@ -0,0 +1,184 @@
+import { ChainTracker } from '@bsv/sdk'
+import { BaseBlockHeader, BlockHeader } from './BlockHeaderApi'
+import { Chain } from '../../../../sdk/types'
+
+/**
+ * @public
+ */
+export type HeaderListener = (header: BlockHeader) => void
+
+/**
+ * @public
+ */
+export type ReorgListener = (depth: number, oldTip: BlockHeader, newTip: BlockHeader) => void
+
+/**
+ * @public
+ */
+export interface ChaintracksPackageInfoApi {
+  name: string
+  version: string
+}
+
+/**
+ * @public
+ */
+export interface ChaintracksInfoApi {
+  chain: Chain
+  heightBulk: number
+  heightLive: number
+  storage: string
+  bulkIngestors: string[]
+  liveIngestors: string[]
+  packages: ChaintracksPackageInfoApi[]
+}
+
+/**
+ * Chaintracks client API excluding events and callbacks
+ * @public
+ */
+export interface ChaintracksClientApi extends ChainTracker {
+  /**
+   * Confirms the chain
+   */
+  getChain(): Promise<Chain>
+
+  /**
+   * @returns Summary of configuration and state.
+   */
+  getInfo(): Promise<ChaintracksInfoApi>
+
+  /**
+   * Return the latest chain height from configured bulk ingestors.
+   */
+  getPresentHeight(): Promise<number>
+
+  /**
+   * Adds headers in 80 byte serialized format to an array.
+   * Only adds active headers.
+   * array length divided by 80 is the actual number returned.
+   *
+   * @param height of first header
+   * @param count of headers, maximum
+   * @returns array of headers as serialized hex string
+   */
+  getHeaders(height: number, count: number): Promise<string>
+
+  /**
+   * Returns the active chain tip header
+   */
+  findChainTipHeader(): Promise<BlockHeader>
+
+  /**
+   * Returns the block hash of the active chain tip.
+   */
+  findChainTipHash(): Promise<string>
+
+  /**
+   * Returns block header for a given block height on active chain.
+   */
+  findHeaderForHeight(height: number): Promise<BlockHeader | undefined>
+
+  /**
+   * Returns block header for a given recent block hash or undefined.
+   * @param hash
+   */
+  findHeaderForBlockHash(hash: string): Promise<BlockHeader | undefined>
+
+  /**
+   * Submit a possibly new header for adding
+   *
+   * If the header is invalid or a duplicate it will not be added.
+   *
+   * This header will be ignored if the previous header has not already been inserted when this header
+   * is considered for insertion.
+   *
+   * @param header
+   * @returns immediately
+   */
+  addHeader(header: BaseBlockHeader): Promise<void>
+
+  /**
+   * Start or resume listening for new headers.
+   *
+   * Calls `synchronize` to catch up on headers that were found while not listening.
+   *
+   * Begins listening to any number of configured new header notification services.
+   *
+   * Begins sending notifications to subscribed listeners only after processing any
+   * previously found headers.
+   *
+   * May be called if already listening or synchronizing to listen.
+   *
+   * The `listening` API function which returns a Promise can be awaited.
+   */
+  startListening(): Promise<void>
+
+  /**
+   * Returns a Promise that will resolve when the previous call to startListening
+   * enters the listening-for-new-headers state.
+   */
+  listening(): Promise<void>
+
+  /**
+   * Returns true if actively listening for new headers and client api is enabled.
+   */
+  isListening(): Promise<boolean>
+
+  /**
+   * Returns true if `synchronize` has completed at least once.
+   */
+  isSynchronized(): Promise<boolean>
+
+  /**
+   * Subscribe to "header" events.
+   * @param listener
+   * @returns identifier for this subscription
+   * @throws ERR_NOT_IMPLEMENTED if callback events are not supported
+   */
+  subscribeHeaders(listener: HeaderListener): Promise<string>
+
+  /**
+   * Subscribe to "reorganization" events.
+   * @param listener
+   * @returns identifier for this subscription
+   * @throws ERR_NOT_IMPLEMENTED if callback events are not supported
+   */
+  subscribeReorgs(listener: ReorgListener): Promise<string>
+
+  /**
+   * Cancels all subscriptions with the given `subscriptionId` which was previously returned
+   * by a `subscribe` method.
+   * @param subscriptionId value previously returned by subscribeToHeaders or subscribeToReorgs
+   * @returns true if a subscription was canceled
+   * @throws ERR_NOT_IMPLEMENTED if callback events are not supported
+   */
+  unsubscribe(subscriptionId: string): Promise<boolean>
+
+  isValidRootForHeight(root: string, height: number): Promise<boolean>
+  currentHeight: () => Promise<number>
+}
+
+/**
+ * Full Chaintracks API including startListening with callbacks
+ */
+export interface ChaintracksApi extends ChaintracksClientApi {
+  /**
+   * Start or resume listening for new headers.
+   *
+   * Calls `synchronize` to catch up on headers that were found while not listening.
+   *
+   * Begins listening to any number of configured new header notification services.
+   *
+   * Begins sending notifications to subscribed listeners only after processing any
+   * previously found headers.
+   *
+   * May be called if already listening or synchronizing to listen.
+   *
+   * `listening` callback will be called after listening for new live headers has begun.
+   * Alternatively, the `listening` API function which returns a Promise can be awaited.
+   *
+   * @param listening callback indicates when listening for new headers has started.
+   */
+  startListening(listening?: () => void): Promise<void>
+}

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

@@ -0,0 +1,8 @@
+import { HttpClient } from '@bsv/sdk'
+
+export interface ChaintracksFetchApi {
+  httpClient: HttpClient
+  download(url: string): Promise<Uint8Array>
+  fetchJson<R>(url: string): Promise<R>
+  pathJoin(baseUrl: string, subpath: string): string
+}

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

@@ -0,0 +1,58 @@
+/**
+ * Supports access to named data storage (file like).
+ */
+export interface ChaintracksReadableFileApi {
+  path: string
+  close(): Promise<void>
+  /**
+   * Returns the length of the data storage in bytes.
+   */
+  getLength(): Promise<number>
+  /**
+   *
+   * @param length requested length to be returned, may return less than requested.
+   * @param offset starting offset in the existing data storage to read from, defaults to 0.
+   */
+  read(length?: number, offset?: number): Promise<Uint8Array>
+}
+
+/**
+ * Supports access and appending data to new or existing named data storage.
+ * New data is always appended to the end of existing data.
+ */
+export interface ChaintracksAppendableFileApi extends ChaintracksReadableFileApi {
+  /**
+   * @param data data to add to the end of existing data.
+   */
+  append(data: Uint8Array): Promise<void>
+}
+
+/**
+ * Supports creation or re-creation of named data storage from position 0.
+ * Any pre-existing data is initially removed.
+ * Does not support reading existing data.
+ */
+export interface ChaintracksWritableFileApi {
+  path: string
+  close(): Promise<void>
+  /**
+   * @param data data to add to the end of existing data.
+   */
+  append(data: Uint8Array): Promise<void>
+}
+
+/**
+ * Supports file-like access to named data storage.
+ *
+ * Only minimal functionality required by Chaintracks is supported.
+ */
+export interface ChaintracksFsApi {
+  delete(path: string): Promise<void>
+  writeFile(path: string, data: Uint8Array): Promise<void>
+  readFile(path: string): Promise<Uint8Array>
+  openReadableFile(path: string): Promise<ChaintracksReadableFileApi>
+  openWritableFile(path: string): Promise<ChaintracksWritableFileApi>
+  openAppendableFile(path: string): Promise<ChaintracksAppendableFileApi>
+
+  pathJoin(...parts: string[]): string
+}