@bsv/wallet-toolbox 1.7.18 → 2.0.0-beta.0

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

@@ -1,189 +0,0 @@
-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,
-  deactivatedHeaders?: 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

@@ -1,18 +0,0 @@
-import { HttpClient } from '@bsv/sdk'
-
-/**
- * Provides a simplified interface based on the @bsv/sdk `HttpClient` class
- * with just the methods necesary for most Chaintracks operations.
- *
- * The primary purpose is to isolate and centralize external package dependency.
- *
- * Specific ingestors are free to use other means for access.
- *
- * The `ChaintracksFetch` class implements this interface.
- */
-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

@@ -1,58 +0,0 @@
-/**
- * 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
-}

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

@@ -1,386 +0,0 @@
-import { HeightRange } from '../util/HeightRange'
-import { BaseBlockHeader, BlockHeader, LiveBlockHeader } from './BlockHeaderApi'
-import { Chain } from '../../../../sdk/types'
-import { BulkHeaderFileInfo } from '../util/BulkHeaderFile'
-import { BulkFileDataManager } from '../util/BulkFileDataManager'
-
-/// StorageEngine Interface
-
-export interface ChaintracksStorageBaseOptions {
-  /**
-   * Which chain is being tracked: main, test, or stn.
-   */
-  chain: Chain
-
-  /**
-   * How much of recent history is required to be kept in "live" block header storage.
-   *
-   * Headers with height less than active chain tip height minus `liveHeightThreshold`
-   * are not required to be kept in "live" storage and may be migrated to "bulk" storage.
-   *
-   * As no forks, orphans, or reorgs can affect "bulk" block header storage, an
-   * aggressively high number is recommended: At least an order of magnitude more than
-   * the deepest actual reorg you can imagine.
-   */
-  liveHeightThreshold: number
-
-  /**
-   * How much of recent history must be processed with full validation and reorg support.
-   *
-   * Must be less than or equal to `liveHeightThreshold`.
-   *
-   * Headers with height older than active chain tip height minus `reorgHeightThreshold`
-   * may use batch processing when ingesting headers.
-   */
-  reorgHeightThreshold: number
-
-  /**
-   * How many excess "live" headers to accumulate before migrating them as a chunk to the
-   * bulk header storage.
-   */
-  bulkMigrationChunkSize: number
-
-  /**
-   * Maximum number of headers per call to batchInsert
-   */
-  batchInsertLimit: number
-
-  /**
-   * Controls in memory caching and retrieval of missing bulk header data.
-   */
-  bulkFileDataManager: BulkFileDataManager | undefined
-}
-
-export interface ChaintracksStorageQueryApi {
-  log: (...args: any[]) => void
-
-  /**
-   * Returns the active chain tip header
-   * Throws an error if there is no tip.
-   */
-  findChainTipHeader(): Promise<LiveBlockHeader>
-
-  /**
-   * Returns the block hash of the active chain tip.
-   */
-  findChainTipHash(): Promise<string>
-
-  /**
-   * Returns the active chain tip header or undefined if there is no tip.
-   */
-  findChainTipHeaderOrUndefined(): Promise<LiveBlockHeader | undefined>
-
-  /**
-   * Returns the chainWork value of the active chain tip
-   */
-  findChainTipWork(): Promise<string>
-
-  /**
-   * Returns block header for a given block height on active chain.
-   * @param hash block hash
-   */
-  findHeaderForHeight(height: number): Promise<LiveBlockHeader | BlockHeader>
-
-  /**
-   * Returns block header for a given block height on active chain.
-   * @param hash block hash
-   */
-  findHeaderForHeightOrUndefined(height: number): Promise<LiveBlockHeader | BlockHeader | undefined>
-
-  /**
-   * Given two chain tip headers in a chain reorg scenario,
-   * return their common ancestor header.
-   * @param header1 First header in live part of the chain.
-   * @param header2 Second header in live part of the chain.
-   */
-  findCommonAncestor(header1: LiveBlockHeader, header2: LiveBlockHeader): Promise<LiveBlockHeader>
-
-  /**
-   * This is an original API. Proposed deprecation in favor of `findCommonAncestor`
-   * Given two headers that are both chain tips in a reorg scenario, returns
-   * the depth of the reorg (the greater of the heights of the two provided
-   * headers, minus the height of their last common ancestor)
-   */
-  findReorgDepth(header1: LiveBlockHeader, header2: LiveBlockHeader): Promise<number>
-
-  /**
-   * Returns true if the given merkleRoot is found in a block header on the active chain.
-   * @param merkleRoot of block header
-   */
-  isMerkleRootActive(merkleRoot: string): Promise<boolean>
-
-  /**
-   * Returns serialized headers as a Uint8Array.
-   * Only adds bulk and active live headers.
-   *
-   * @param height is the minimum header height to return, must be >= zero.
-   * @param count height + count - 1 is the maximum header height to return.
-   * @returns serialized headers as a Uint8Array.
-   */
-  getHeadersUint8Array(height: number, count: number): Promise<Uint8Array>
-
-  /**
-   * Returns an array of deserialized headers.
-   * Only adds bulk and active live headers.
-   *
-   * @param height is the minimum header height to return, must be >= zero.
-   * @param count height + count - 1 is the maximum header height to return.
-   * @returns array of deserialized headers
-   */
-  getHeaders(height: number, count: number): Promise<BaseBlockHeader[]>
-
-  /**
-   * Returns active `LiveBlockHeaders` with height in the given range.
-   *
-   * @param range
-   * @returns array of active `LiveBlockHeaders`
-   */
-  getLiveHeaders(range: HeightRange): Promise<LiveBlockHeader[]>
-
-  /**
-   * Returns serialized bulk headers in the given range.
-   *
-   * @param range
-   * @returns serialized headers as a Uint8Array.
-   */
-  getBulkHeaders(range: HeightRange): Promise<Uint8Array>
-
-  /**
-   * Returns block header for a given block height on active chain.
-   * @param hash block hash
-   */
-  findLiveHeaderForHeight(height: number): Promise<LiveBlockHeader | null>
-
-  /**
-     * Returns block header for a given headerId.
-     
-     * Only from the "live" portion of the chain.
-     * @param headerId
-     */
-  findLiveHeaderForHeaderId(headerId: number): Promise<LiveBlockHeader>
-
-  /**
-   * Returns block header for a given block hash.
-   * Only from the "live" portion of the chain.
-   * Returns null if not found.
-   * @param hash block hash
-   */
-  findLiveHeaderForBlockHash(hash: string): Promise<LiveBlockHeader | null>
-
-  /**
-   * Returns block header for a given merkleRoot.
-   * Only from the "live" portion of the chain.
-   * @param merkleRoot
-   */
-  findLiveHeaderForMerkleRoot(merkleRoot: string): Promise<LiveBlockHeader | null>
-
-  /**
-   * Returns the height range of both bulk and live storage.
-   * Verifies that the ranges meet these requirements:
-   * - Both may be empty.
-   * - If bulk is empty, live must be empty or start with height zero.
-   * - If bulk is not empty it must start with height zero.
-   * - If bulk is not empty and live is not empty, live must start with the height after bulk.
-   */
-  getAvailableHeightRanges(): Promise<{ bulk: HeightRange; live: HeightRange }>
-
-  /**
-   * @returns The current minimum and maximum height active LiveBlockHeaders in the "live" database.
-   */
-  findLiveHeightRange(): Promise<HeightRange>
-
-  /**
-   * @returns The maximum headerId value used by existing records or -1 if there are none.
-   */
-  findMaxHeaderId(): Promise<number>
-
-  //
-  // Available Properties
-  //
-
-  /**
-   * Which chain is being tracked: "main" or "test".
-   */
-  chain: Chain
-
-  /**
-   * How much of recent history is required to be kept in "live" block header storage.
-   *
-   * Headers with height older than active chain tip height minus `liveHeightThreshold`
-   * are not required to be kept in "live" storage and may be migrated to "bulk" storage.
-   */
-  liveHeightThreshold: number
-
-  /**
-   * How much of recent history must be processed with full validation and reorg support.
-   *
-   * May be less than `liveHeightThreshold`.
-   *
-   * Headers with height older than active chain tip height minus ``
-   * may use batch processing when ingesting headers.
-   */
-  reorgHeightThreshold: number
-
-  /**
-   * How many excess "live" headers to accumulate before migrating them as a chunk to the
-   * bulk header storage.
-   */
-  bulkMigrationChunkSize: number
-
-  /**
-   * Maximum number of headers per call to batchInsert
-   */
-  batchInsertLimit: number
-}
-
-export type InsertHeaderResult = {
-  /**
-   * true only if the new header was inserted
-   */
-  added: boolean
-  /**
-   * true only if the header was not inserted because a matching hash already exists in the database.
-   */
-  dupe: boolean
-  /**
-   * true only if the new header became the active chain tip.
-   */
-  isActiveTip: boolean
-  /**
-   * zero if the insertion of the new header did not cause a reorg.
-   * If isActiveTip is true, and priorTip is not the new headers previous header,
-   * then the minimum height difference from the common active ancestor to this header (new tip) and priorTip.
-   */
-  reorgDepth: number
-  /**
-   * If `added` is true, this header was the active chain tip before the insert. It may or may not still be the active chain tip after the insert.
-   */
-  priorTip: LiveBlockHeader | undefined
-  /**
-   * If a reorg has occurred, these headers where active and are now deactivated.
-   */
-  deactivatedHeaders: LiveBlockHeader[]
-  /**
-   * header's previousHash was not found in database
-   */
-  noPrev: boolean
-  /**
-   * header matching previousHash does not have height - 1
-   */
-  badPrev: boolean
-  /**
-   * an active ancestor was not found in live storage or prev header.
-   */
-  noActiveAncestor: boolean
-  /**
-   * a current chain tip was not found in live storage or prev header.
-   */
-  noTip: boolean
-}
-
-export interface ChaintracksStorageBulkFileApi {
-  insertBulkFile(file: BulkHeaderFileInfo): Promise<number>
-  updateBulkFile(fileId: number, file: BulkHeaderFileInfo): Promise<number>
-  deleteBulkFile(fileId: number): Promise<number>
-  getBulkFiles(): Promise<BulkHeaderFileInfo[]>
-  getBulkFileData(fileId: number, offset?: number, length?: number): Promise<Uint8Array | undefined>
-}
-
-export interface ChaintracksStorageIngestApi {
-  log: (...args: any[]) => void
-
-  /**
-   * Attempts to insert a block header into the chain.
-   *
-   * Returns 'added' false and 'dupe' true if header's hash already exists in the live database
-   * Returns 'added' false and 'dupe' false if header's previousHash wasn't found in the live database, or height doesn't increment previous' height.
-   *
-   * Computes the header's chainWork from its bits and the previous header's chainWork.
-   *
-   * Returns 'added' true if the header was added to the live database.
-   * Returns 'isActiveTip' true if header's chainWork is greater than current active chain tip's chainWork.
-   *
-   * If the addition of this header caused a reorg (did not directly extend old active chain tip):
-   * Returns 'reorgDepth' the minimum height difference of the common ancestor to the two chain tips.
-   * Returns 'priorTip' the old active chain tip.
-   * If not a reorg:
-   * Returns 'reorgDepth' of zero.
-   * Returns 'priorTip' the active chain tip before this insert. May be unchanged.
-   *
-   * Implementation must call `pruneLiveBlockHeaders` after adding new header.
-   *
-   * @param header to insert
-   * @param prev if not undefined, the last bulk storage header with total bulk chainWork
-   */
-  insertHeader(header: BlockHeader, prev?: LiveBlockHeader): Promise<InsertHeaderResult>
-
-  /**
-   * Must be called after the addition of new LiveBlockHeaders.
-   *
-   * Checks the `StorageEngine` configuration options to see
-   * if BulkStorage is configured and if there is at least one
-   * `bulkMigrationChunkSize` woth of headers in excess of
-   * `liveHeightThreshold` available.
-   *
-   * If yes, then calls `migrateLiveToBulk` one or more times.
-   * @param activeTipHeight height of active tip after adds
-   */
-  pruneLiveBlockHeaders(activeTipHeight: number): Promise<void>
-
-  /**
-   * Migrates the oldest `count` LiveBlockHeaders to BulkStorage.
-   * BulkStorage must be configured.
-   * `count` must not exceed `bulkMigrationChunkSize`.
-   * `count` must leave at least `liveHeightThreshold` LiveBlockHeaders.
-   *
-   * @param count
-   *
-   * Steps:
-   * - Copy count oldest active LiveBlockHeaders from live database to buffer.
-   * - Append the buffer of headers to BulkStorage
-   * - Add the buffer's BlockHash, Height pairs to corresponding index table.
-   * - Add the buffer's MerkleRoot, Height pairs to corresponding index table.
-   * - Delete the records from the live database.
-   */
-  migrateLiveToBulk(count: number): Promise<void>
-
-  /**
-   * Delete live headers with height less or equal to `maxHeight`
-   * after they have been migrated to bulk storage.
-   *
-   * @param maxHeight delete all records with less or equal `height`
-   */
-  deleteOlderLiveBlockHeaders(maxHeight: number): Promise<number>
-
-  /**
-   * Async initialization method.
-   *
-   * May be called prior to other async methods to control when initialization occurs.
-   */
-  makeAvailable(): Promise<void>
-
-  /**
-   * Migrate storage schema to latest schema changes.
-   *
-   * Typically invoked automatically by `makeAvailable`.
-   */
-  migrateLatest(): Promise<void>
-
-  dropAllData(): Promise<void>
-
-  /**
-   * Release all resources. Makes the instance unusable.
-   */
-  destroy(): Promise<void>
-}
-
-export interface ChaintracksStorageApi extends ChaintracksStorageQueryApi, ChaintracksStorageIngestApi {
-  log: (...args: any[]) => void
-
-  bulkManager: BulkFileDataManager
-
-  /**
-   * Close and release all resources.
-   */
-  destroy(): Promise<void>
-}

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

@@ -1,25 +0,0 @@
-import { BlockHeader } from './BlockHeaderApi'
-import { ChaintracksStorageApi } from './ChaintracksStorageApi'
-
-/* eslint-disable @typescript-eslint/no-empty-interface */
-export interface LiveIngestorApi {
-  /**
-   * Close and release all resources.
-   */
-  shutdown(): Promise<void>
-
-  getHeaderByHash(hash: string): Promise<BlockHeader | undefined>
-
-  /**
-   * 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
-
-  startListening(liveHeaders: BlockHeader[]): Promise<void>
-
-  stopListening(): void
-}