@bsv/wallet-toolbox 1.6.11 → 1.6.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bsv/wallet-toolbox",
-  "version": "1.6.11",
+  "version": "1.6.14",
   "description": "BRC100 conforming wallet, wallet storage and wallet signer components",
   "main": "./out/src/index.js",
   "types": "./out/src/index.d.ts",

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

@@ -1,5 +1,15 @@
 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>

package/src/services/chaintracker/chaintracks/ChaintracksService.ts

@@ -1,7 +1,7 @@
 import { Chaintracks } from './Chaintracks'
 
 import { IncomingMessage, Server, ServerResponse } from 'http'
-import express from 'express'
+import express, { Request, Response } from 'express'
 import bodyParser from 'body-parser'
 import { Chain } from '../../../sdk/types'
 import { createNoDbChaintracksOptions } from './createDefaultNoDbChaintracksOptions'
@@ -85,6 +85,16 @@ export class ChaintracksService {
       }
     })
 
+    app.get(`/robots.txt`, (req: Request, res: Response) => {
+      res.type('text/plain')
+      res.send(`User-agent: *\nDisallow: /`)
+    })
+
+    app.get(`/`, (req: Request, res: Response) => {
+      res.type('text/plain')
+      res.send(`Chaintracks ${this.chain}Net Block Header Service`)
+    })
+
     const handleErr = (err: any, res: any) => {
       res.status(500).json({
         status: 'error',

package/src/services/chaintracker/chaintracks/Storage/ChaintracksStorageIdb.ts

@@ -39,9 +39,23 @@ export class ChaintracksStorageIdb extends ChaintracksStorageBase implements Cha
     this.dbName = `chaintracks-${this.chain}net`
   }
 
+  override async makeAvailable(): Promise<void> {
+    if (this.isAvailable && this.hasMigrated) return
+    // Not a base class policy, but we want to ensure migrations are run before getting to business.
+    if (!this.hasMigrated) {
+      await this.migrateLatest()
+    }
+    if (!this.isAvailable) {
+      await super.makeAvailable()
+      // Connect the bulk data file manager to the table provided by this storage class.
+      await this.bulkManager.setStorage(this, this.log)
+    }
+  }
+
   override async migrateLatest(): Promise<void> {
     if (this.db) return
     this.db = await this.initDB()
+    await super.migrateLatest()
   }
 
   override async destroy(): Promise<void> {}

package/src/services/chaintracker/chaintracks/__tests/Chaintracks.test.ts

@@ -4,6 +4,7 @@ import { wait } from '../../../../utility/utilityHelpers'
 import { Chain } from '../../../../sdk'
 import { createNoDbChaintracksOptions } from '../createDefaultNoDbChaintracksOptions'
 import { ChaintracksFs } from '../util/ChaintracksFs'
+import { LocalCdnServer } from './LocalCdnServer'
 
 const rootFolder = './src/services/chaintracker/chaintracks/__tests/data'
 
@@ -39,6 +40,17 @@ describe('Chaintracks tests', () => {
     await NoDbBody('test', true)
   })
 
+  test.skip('5 run local CDN on port 8300', async () => {
+    const fs = ChaintracksFs
+    const server = new LocalCdnServer(8300, fs.pathJoin(rootFolder, 'export'))
+    await server.start()
+    let done = false
+    for (; !done; ) {
+      await wait(10000)
+    }
+    await server.stop()
+  })
+
   async function NoDbBody(chain: Chain, exportHeaders?: boolean) {
     const o = createNoDbChaintracksOptions(chain)
     const c = new Chaintracks(o)

package/src/services/chaintracker/chaintracks/__tests/createIdbChaintracks.test.ts

@@ -16,7 +16,8 @@ describe('createIdbChaintracks tests', () => {
     const target: Chain = 'main'
     if (_tu.noEnv(target)) return
     const env = _tu.getEnv(target)
-    const { chain, chaintracks, storage } = await createIdbChaintracks(env.chain, env.whatsonchainApiKey)
+    const { chain, chaintracks, storage, available } = await createIdbChaintracks(env.chain, env.whatsonchainApiKey)
+    await available
     const headerListener: HeaderListener = (header: BlockHeader) => {
       console.log(`headerListener: height: ${header.height} hash: ${header.hash} ${new Date().toISOString()}`)
     }

package/src/services/chaintracker/chaintracks/util/BulkFileDataManager.ts

@@ -192,11 +192,8 @@ export class BulkFileDataManager {
       } else if (isBdfIncremental(vbf) && lbf && isBdfIncremental(lbf)) {
         await this.mergeIncremental(lbf, vbf, r)
       } else {
-        const added = this.add(vbf)
+        const added = await this.add(vbf)
         r.inserted.push(added)
-        if (this.storage) {
-          vbf.fileId = await this.storage.insertBulkFile(added)
-        }
       }
     }
     this.log(`BulkFileDataManager.merge:\n${this.toLogString(r)}\n`)
@@ -515,13 +512,17 @@ export class BulkFileDataManager {
     }
   }
 
-  private add(bfd: BulkFileData): BulkHeaderFileInfo {
+  private async add(bfd: BulkFileData): Promise<BulkHeaderFileInfo> {
     this.validateBfdForAdd(bfd)
     const index = this.bfds.length
     this.bfds.push(bfd)
     this.fileHashToIndex[bfd.fileHash] = index
     this.ensureMaxRetained()
-    return bfdToInfo(bfd, true)
+    const info = bfdToInfo(bfd, true)
+    if (this.storage) {
+      info.fileId = bfd.fileId = await this.storage.insertBulkFile(info)
+    }
+    return info
   }
 
   private replaceBfdAtIndex(index: number, update: BulkFileData): void {

package/src/services/chaintracker/chaintracks/util/ChaintracksFetch.ts

@@ -1,6 +1,10 @@
 import { defaultHttpClient, HttpClient } from '@bsv/sdk'
 import { ChaintracksFetchApi } from '../Api/ChaintracksFetchApi'
 
+/**
+ * This class implements the ChaintracksFetchApi
+ * using the @bsv/sdk `defaultHttpClient`.
+ */
 export class ChaintracksFetch implements ChaintracksFetchApi {
   httpClient: HttpClient = defaultHttpClient()
 

package/src/services/chaintracker/chaintracks/util/ChaintracksFs.ts

@@ -38,6 +38,10 @@ export abstract class ChaintracksFsStatics {
   }
 }
 
+/**
+ * This object is an implementation of the `ChaintracksFsApi` interface
+ * using the `fs` package which may not be available in all environments.
+ */
 export const ChaintracksFs: ChaintracksFsApi = ChaintracksFsStatics
 
 export class ChaintracksReadableFile implements ChaintracksReadableFileApi {

package/src/services/chaintracker/chaintracks/util/HeightRange.ts

@@ -10,16 +10,32 @@ export interface HeightRanges {
   live: HeightRange
 }
 
+/**
+ * Represents a range of block heights.
+ *
+ * Operations support integrating contiguous batches of headers,
+ */
 export class HeightRange implements HeightRangeApi {
   constructor(
     public minHeight: number,
     public maxHeight: number
   ) {}
 
+  /**
+   * All ranges where maxHeight is less than minHeight are considered empty.
+   * The canonical empty range is (0, -1).
+   */
   static readonly empty = new HeightRange(0, -1)
 
   /**
-   * @param headers
+   * @returns true iff minHeight is greater than maxHeight.
+   */
+  get isEmpty() {
+    return this.minHeight > this.maxHeight
+  }
+
+  /**
+   * @param headers an array of objects with a non-negative integer `height` property.
    * @returns range of height values from the given headers, or the empty range if there are no headers.
    */
   static from(headers: BlockHeader[]): HeightRange {
@@ -29,14 +45,16 @@ export class HeightRange implements HeightRangeApi {
     return new HeightRange(minHeight, maxHeight)
   }
 
+  /**
+   * @returns the number of heights in the range, or 0 if the range is empty.
+   */
   get length() {
     return Math.max(0, this.maxHeight - this.minHeight + 1)
   }
 
-  get isEmpty() {
-    return this.minHeight > this.maxHeight
-  }
-
+  /**
+   * @returns an easy to read string representation of the height range.
+   */
   toString(): string {
     return this.isEmpty ? '<empty>' : `${this.minHeight}-${this.maxHeight}`
   }

package/src/services/chaintracker/chaintracks/util/validBulkHeaderFilesByFileHash.ts

@@ -1,5 +1,29 @@
 import { BulkHeaderFileInfo } from './BulkHeaderFile'
 
+/**
+ * Compares meta data received for a bulk header file `vbf` to known
+ * valid bulk header files based on their `fileHash`.
+ *
+ * Short circuits both the retreival and validation of individual headers,
+ * only a single SHA256 hash of the aggregate data needs to be compared.
+ *
+ * The standard file size for historic block headers is 100,000 per file
+ * which results in a many orders of magnitude initialization speedup.
+ *
+ * The following properties must match:
+ * - `firstHeight`
+ * - `count`
+ * - `prevChainWork`
+ * - `prevHash`
+ * - `lastChainWork`
+ * - `lastHash`
+ * - `chain`
+ *
+ * @param vbf
+ * @returns true iff bulk file meta data (excluding its source) matches a known file.
+ *
+ * @publicbody
+ */
 export function isKnownValidBulkHeaderFile(vbf: BulkHeaderFileInfo): boolean {
   if (!vbf || !vbf.fileHash) return false
   const bf = validBulkHeaderFilesByFileHash()[vbf.fileHash]
@@ -20,6 +44,10 @@ export function isKnownValidBulkHeaderFile(vbf: BulkHeaderFileInfo): boolean {
 
 let _validBulkHeaderFilesByFileHash: Record<string, BulkHeaderFileInfo> | undefined
 
+/**
+ * Hash map of known valid bulk header files by their `fileHash`.
+ * @returns object where keys are file hashes of known bulk header files.
+ */
 export function validBulkHeaderFilesByFileHash(): Record<string, BulkHeaderFileInfo> {
   if (!_validBulkHeaderFilesByFileHash) {
     _validBulkHeaderFilesByFileHash = {}
@@ -32,6 +60,10 @@ export function validBulkHeaderFilesByFileHash(): Record<string, BulkHeaderFileI
   return _validBulkHeaderFilesByFileHash
 }
 
+/**
+ * Static array of known valid bulk header files.
+ * `sourceUrl` is included only as a reference to the original certifying authority.
+ */
 export const validBulkHeaderFiles: BulkHeaderFileInfo[] = [
   {
     sourceUrl: 'https://cdn.projectbabbage.com/blockheaders',

package/src/storage/remoting/StorageServer.ts

@@ -68,7 +68,7 @@ export class StorageServer {
 
     this.app.get(`/`, (req: Request, res: Response) => {
       res.type('text/plain')
-      res.send(`BRC-100 Storage Provider.`)
+      res.send(`BRC-100 ${this.wallet.chain}Net Storage Provider.`)
     })
 
     const options: AuthMiddlewareOptions = {