@bsv/wallet-toolbox 1.3.25 → 1.3.26

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bsv/wallet-toolbox",
-  "version": "1.3.25",
+  "version": "1.3.26",
   "description": "BRC100 conforming wallet, wallet storage and wallet signer components",
   "main": "./out/src/index.js",
   "types": "./out/src/index.d.ts",
@@ -32,7 +32,7 @@
   "dependencies": {
     "@bsv/auth-express-middleware": "^1.1.2",
     "@bsv/payment-express-middleware": "^1.0.6",
-    "@bsv/sdk": "^1.5.1",
+    "@bsv/sdk": "^1.5.2",
     "express": "^4.21.2",
     "idb": "^8.0.2",
     "knex": "^3.1.0",

package/src/sdk/WalletServices.interfaces.ts

@@ -168,6 +168,12 @@ export interface WalletServices {
    * @param txid
    */
   getBeefForTxid(txid: string): Promise<Beef>
+
+  /**
+   * @param reset if true, ends current interval and starts a new one.
+   * @returns a history of service calls made to the configured services.
+   */
+  getServicesCallHistory(reset?: boolean) : ServicesCallHistory
 }
 
 export type ScriptHashFormat = 'hashLE' | 'hashBE' | 'script'
@@ -497,3 +503,100 @@ export type UpdateFiatExchangeRateService = (
   targetCurrencies: string[],
   options: WalletServicesOptions
 ) => Promise<FiatExchangeRates>
+
+/**
+ * Type for the service call history returned by Services.getServicesCallHistory.
+ */
+export type ServicesCallHistory = {
+  version: number
+  getMerklePath: ServiceCallHistory
+  getRawTx: ServiceCallHistory
+  postBeef: ServiceCallHistory
+  getUtxoStatus: ServiceCallHistory
+  getStatusForTxids: ServiceCallHistory
+  getScriptHashHistory: ServiceCallHistory
+  updateFiatExchangeRates: ServiceCallHistory
+}
+
+/**
+ * Minimum data tracked for each service call.
+ */
+export interface ServiceCall {
+  /**
+   * string value must be Date's toISOString format.
+   */
+  when: Date | string
+  msecs: number
+  /**
+   * true iff service provider successfully processed the request
+   * false iff service provider failed to process the request which includes thrown errors.
+   */
+  success: boolean
+  /**
+   * Simple text summary of result. e.g. `not a valid utxo` or `valid utxo`
+   */
+  result?: string
+  /**
+   * Error code and message iff success is false and a exception was thrown.
+   */
+  error?: { message: string, code: string }
+}
+
+/**
+ * Counts of service calls over a time interval.
+ */
+export interface ServiceCallHistoryCounts {
+  /**
+   * count of calls returning success true.
+   */
+  success: number
+  /**
+   * count of calls returning success false.
+   */
+  failure: number
+  /**
+   * of failures (success false), count of calls with valid error code and message.
+   */
+  error: number
+  /**
+   * Counts are of calls over interval `since` to `until`.
+   * string value must be Date's toISOString format.
+   */
+  since: Date | string
+  /**
+   * Counts are of calls over interval `since` to `until`.
+   * string value must be Date's toISOString format.
+   */
+  until: Date | string
+}
+
+/**
+ * History of service calls for a single service, single provider.
+ */
+export interface ProviderCallHistory {
+  providerName: string
+  serviceName: string
+  /**
+   * Most recent service calls.
+   * Array length is limited by Services configuration.
+   */
+  calls: ServiceCall[]
+  /**
+   * Counts since creation of Services instance.
+   */
+  totalCounts: ServiceCallHistoryCounts
+  /**
+   * Entry [0] is always the current interval being extended by new calls.
+   * when `getServiceCallHistory` with `reset` true is called, a new interval with zero counts is added to the start of array.
+   * Array length is limited by Services configuration.
+   */
+  resetCounts: ServiceCallHistoryCounts[]
+}
+
+/**
+ * History of service calls for a single service, all providers.
+ */
+export interface ServiceCallHistory {
+  serviceName: string
+  historyByProvider: Record<string, ProviderCallHistory>
+}

package/src/services/ServiceCollection.ts

@@ -1,13 +1,20 @@
 import { WalletError } from "../sdk/WalletError";
+import { ProviderCallHistory, ServiceCallHistory } from "../sdk/WalletServices.interfaces";
+
+const MAX_RESET_COUNTS = 32
+const MAX_CALL_HISTORY = 32
 
 export class ServiceCollection<T> {
-  since: Date
   services: { name: string; service: T }[]
   _index: number
 
-  _callHistory: Record<string, ServiceCallHistory> = {}
+  /**
+   * Start of currentCounts interval. Initially instance construction time.
+   */
+  readonly since: Date
+  _historyByProvider: Record<string, ProviderCallHistory> = {}
 
-  constructor(services?: { name: string; service: T }[]) {
+  constructor(public serviceName: string, services?: { name: string; service: T }[]) {
     this.services = services || []
     this._index = 0
     this.since = new Date()
@@ -34,8 +41,8 @@ export class ServiceCollection<T> {
     const i = this._index
     const name = this.services[i].name
     const service = this.services[i].service
-    const call = { name, when: new Date(), durationMsecs: 0, success: false, result: undefined, error: undefined }
-    return { name, service, call }
+    const call = { name, when: new Date(), msecs: 0, success: false, result: undefined, error: undefined }
+    return { serviceName: this.serviceName, providerName: name, service, call }
   }
 
   get allServicesToCall(): ServiceToCall<T>[] {
@@ -68,28 +75,44 @@ export class ServiceCollection<T> {
   }
 
   clone(): ServiceCollection<T> {
-    return new ServiceCollection([...this.services])
+    return new ServiceCollection(this.serviceName, [...this.services])
   }
 
-  _addServiceCall(name: string, call: ServiceCall): ServiceCallHistory {
-    let h = this._callHistory[name]
+  _addServiceCall(providerName: string, call: ServiceCall): ProviderCallHistory {
+    const now = new Date()
+    let h = this._historyByProvider[providerName]
     if (!h) {
-      h = { name, calls: [], count: 0, countError: 0, countFailure: 0, countSuccess: 0, since: this.since }
-      this._callHistory[name] = h
+      h = {
+        serviceName: this.serviceName,
+        providerName: providerName,
+        calls: [],
+        totalCounts: { success: 0, failure: 0, error: 0, since: this.since, until: now },
+        resetCounts: [{ success: 0, failure: 0, error: 0, since: this.since, until: now }]
+      }
+      this._historyByProvider[providerName] = h
     }
-    h.calls.push(call)
-    h.count++
-    h.calls = h.calls.slice(-32)
+    h.calls.unshift(call)
+    h.calls = h.calls.slice(0,MAX_CALL_HISTORY)
+    h.totalCounts.until = now
+    h.resetCounts[0].until = now
     return h
   }
 
+  getDuration(since: Date | string): number {
+    const now = new Date()
+    if (typeof since === 'string') since = new Date(since)
+    return now.getTime() - since.getTime()
+  }
+
   addServiceCallSuccess(stc: ServiceToCall<T>, result?: string): void {
     const call = stc.call
     call.success = true
     call.result = result
     call.error = undefined
-    call.durationMsecs = new Date().getTime() - call.when.getTime()
-    this._addServiceCall(this.name, call).countSuccess++
+    call.msecs = this.getDuration(call.when)
+    const h = this._addServiceCall(stc.providerName, call)
+    h.totalCounts.success++
+    h.resetCounts[0].success++
   }
 
   addServiceCallFailure(stc: ServiceToCall<T>, result?: string): void {
@@ -97,8 +120,10 @@ export class ServiceCollection<T> {
     call.success = false
     call.result = result
     call.error = undefined
-    call.durationMsecs = new Date().getTime() - call.when.getTime()
-    this._addServiceCall(this.name, call).countFailure++
+    call.msecs = this.getDuration(call.when)
+    const h = this._addServiceCall(this.name, call)
+    h.totalCounts.failure++
+    h.resetCounts[0].failure++
   }
 
   addServiceCallError(stc: ServiceToCall<T>, error: WalletError): void {
@@ -106,66 +131,101 @@ export class ServiceCollection<T> {
     call.success = false
     call.result = undefined
     call.error = error
-    call.durationMsecs = new Date().getTime() - call.when.getTime()
-    this._addServiceCall(this.name, call).countError++
+    call.msecs = this.getDuration(call.when)
+    const h = this._addServiceCall(this.name, call)
+    h.totalCounts.failure++
+    h.totalCounts.error++
+    h.resetCounts[0].failure++
+    h.resetCounts[0].error++
   }
 
   /**
    * @returns A copy of current service call history
    */
-  getServiceCallHistory(reset?: boolean): Record<string, ServiceCallHistory> {
-    const histories: Record<string, ServiceCallHistory> = {}
-    for (const name of Object.keys(this._callHistory)) {
-      const h = this._callHistory[name]
-      histories[name] = {
-        name: h.name,
-        count: h.count,
-        countError: h.countError,
-        countFailure: h.countFailure,
-        countSuccess: h.countSuccess,
-        since: h.since,
+  getServiceCallHistory(reset?: boolean): ServiceCallHistory {
+    const now = new Date()
+    const history: ServiceCallHistory = { serviceName: this.serviceName, historyByProvider: {} }
+    for (const name of Object.keys(this._historyByProvider)) {
+      const h = this._historyByProvider[name]
+      const c: ProviderCallHistory = {
+        serviceName: h.serviceName,
+        providerName: h.providerName,
         calls: h.calls.map(c => ({
-          name: c.name,
-          when: c.when,
-          durationMsecs: c.durationMsecs,
+          when: dateToString(c.when),
+          msecs: c.msecs,
           success: c.success,
           result: c.result,
           error: c.error ? { message: c.error.message, code: c.error.code } : undefined
-        }))
+        })),
+        totalCounts: {
+          success: h.totalCounts.success,
+          failure: h.totalCounts.failure,
+          error: h.totalCounts.error,
+          since: dateToString(h.totalCounts.since),
+          until: dateToString(h.totalCounts.until)
+        },
+        resetCounts: []
+      }
+      for (let i = 0; i < h.resetCounts.length; i++) {
+        const r = h.resetCounts[i]
+        c.resetCounts.push({
+          success: r.success,
+          failure: r.failure,
+          error: r.error,
+          since: dateToString(r.since),
+          until: dateToString(r.until)
+        })
       }
+      history.historyByProvider[name] = c
       if (reset) {
-        h.count = 0
-        h.countError = 0
-        h.countFailure = 0
-        h.countSuccess = 0
-        h.since = new Date()
+        // Make sure intervals are continuous.
+        h.resetCounts[0].until = now
+        // insert a new resetCounts interval
+        h.resetCounts.unshift({
+          success: 0,
+          failure: 0,
+          error: 0,
+          // start of new interval
+          since: now,
+          // end of new interval, gets bumped with each new call added
+          until: now
+        })
+        // limit history to most recent intervals
+        h.resetCounts = h.resetCounts.slice(0, MAX_CALL_HISTORY)
       }
     }
-    return histories
+    return history
+
+    function dateToString(d: Date | string): string {
+      return typeof d === 'string' ? d : d.toISOString()
+    }
   }
 }
 
 export interface ServiceCall {
-  name: string
-  when: Date
-  durationMsecs: number
+  /**
+   * string value must be Date's toISOString format.
+   */
+  when: Date | string
+  msecs: number
+  /**
+   * true iff service provider successfully processed the request
+   * false iff service provider failed to process the request which includes thrown errors.
+   */
   success: boolean
+  /**
+   * Simple text summary of result. e.g. `not a valid utxo` or `valid utxo`
+   */
   result?: string
+  /**
+   * Error code and message iff success is false and a exception was thrown.
+   */
   error?: { message: string, code: string }
 }
 
-export interface ServiceCallHistory {
-  name: string
-  calls: ServiceCall[]
-  count: number
-  countSuccess: number
-  countFailure: number
-  countError: number
-  since: Date
-}
-
 export interface ServiceToCall<T> {
-  name: string
+  providerName: string
+  serviceName: string
   service: T
   call: ServiceCall
 }

package/src/services/Services.ts

@@ -1,6 +1,6 @@
 import { Transaction as BsvTransaction, Beef, ChainTracker, Utils } from '@bsv/sdk'
 import { asArray, asString, doubleSha256BE, sdk, sha256Hash, TableOutput, wait } from '../index.client'
-import { ServiceCall, ServiceCollection } from './ServiceCollection'
+import { ServiceCollection } from './ServiceCollection'
 import { createDefaultWalletServicesOptions } from './createDefaultWalletServicesOptions'
 import { ChaintracksChainTracker } from './chaintracker'
 import { WhatsOnChain } from './providers/WhatsOnChain'
@@ -8,6 +8,7 @@ import { updateChaintracksFiatExchangeRates, updateExchangeratesapi } from './pr
 import { ARC } from './providers/ARC'
 import { Bitails } from './providers/Bitails'
 import { getBeefForTxid } from './providers/getBeefForTxid'
+import { ServicesCallHistory } from '../sdk/WalletServices.interfaces'
 
 export class Services implements sdk.WalletServices {
   static createDefaultOptions(chain: sdk.Chain): sdk.WalletServicesOptions {
@@ -45,15 +46,15 @@ export class Services implements sdk.WalletServices {
     this.bitails = new Bitails(this.chain)
 
     //prettier-ignore
-    this.getMerklePathServices = new ServiceCollection<sdk.GetMerklePathService>()
+    this.getMerklePathServices = new ServiceCollection<sdk.GetMerklePathService>('getMerklePath')
       .add({ name: 'WhatsOnChain', service: this.whatsonchain.getMerklePath.bind(this.whatsonchain) })
       .add({ name: 'Bitails', service: this.bitails.getMerklePath.bind(this.bitails) })
 
     //prettier-ignore
-    this.getRawTxServices = new ServiceCollection<sdk.GetRawTxService>()
+    this.getRawTxServices = new ServiceCollection<sdk.GetRawTxService>('getRawTx')
       .add({ name: 'WhatsOnChain', service: this.whatsonchain.getRawTxResult.bind(this.whatsonchain) })
 
-    this.postBeefServices = new ServiceCollection<sdk.PostBeefService>()
+    this.postBeefServices = new ServiceCollection<sdk.PostBeefService>('postBeef')
     if (this.arcGorillaPool) {
       //prettier-ignore
       this.postBeefServices.add({ name: 'GorillaPool', service: this.arcGorillaPool.postBeef.bind(this.arcGorillaPool) })
@@ -66,32 +67,33 @@ export class Services implements sdk.WalletServices {
       ;
 
     //prettier-ignore
-    this.getUtxoStatusServices = new ServiceCollection<sdk.GetUtxoStatusService>()
+    this.getUtxoStatusServices = new ServiceCollection<sdk.GetUtxoStatusService>('getUtxoStatus')
       .add({ name: 'WhatsOnChain', service: this.whatsonchain.getUtxoStatus.bind(this.whatsonchain) })
 
     //prettier-ignore
-    this.getStatusForTxidsServices = new ServiceCollection<sdk.GetStatusForTxidsService>()
+    this.getStatusForTxidsServices = new ServiceCollection<sdk.GetStatusForTxidsService>('getStatusForTxids')
       .add({ name: 'WhatsOnChain', service: this.whatsonchain.getStatusForTxids.bind(this.whatsonchain) })
 
     //prettier-ignore
-    this.getScriptHashHistoryServices = new ServiceCollection<sdk.GetScriptHashHistoryService>()
+    this.getScriptHashHistoryServices = new ServiceCollection<sdk.GetScriptHashHistoryService>('getScriptHashHistory')
       .add({ name: 'WhatsOnChain', service: this.whatsonchain.getScriptHashHistory.bind(this.whatsonchain) })
 
     //prettier-ignore
-    this.updateFiatExchangeRateServices = new ServiceCollection<sdk.UpdateFiatExchangeRateService>()
+    this.updateFiatExchangeRateServices = new ServiceCollection<sdk.UpdateFiatExchangeRateService>('updateFiatExchangeRate')
       .add({ name: 'ChaintracksService', service: updateChaintracksFiatExchangeRates })
       .add({ name: 'exchangeratesapi', service: updateExchangeratesapi })
   }
 
-  getServicesCallHistory(reset?: boolean) {
+  getServicesCallHistory(reset?: boolean) : ServicesCallHistory {
     return {
-      version: 1,
+      version: 2,
       getMerklePath: this.getMerklePathServices.getServiceCallHistory(reset),
       getRawTx: this.getRawTxServices.getServiceCallHistory(reset),
       postBeef: this.postBeefServices.getServiceCallHistory(reset),
       getUtxoStatus: this.getUtxoStatusServices.getServiceCallHistory(reset),
       getStatusForTxids: this.getStatusForTxidsServices.getServiceCallHistory(reset),
-      getScriptHashHistory: this.getScriptHashHistoryServices.getServiceCallHistory(reset)
+      getScriptHashHistory: this.getScriptHashHistoryServices.getServiceCallHistory(reset),
+      updateFiatExchangeRates: this.updateFiatExchangeRateServices.getServiceCallHistory(reset)
     }
   }
 
@@ -319,6 +321,8 @@ export class Services implements sdk.WalletServices {
 
         if (r.error)
           services.addServiceCallError(stc, r.error)
+        else if (!r.rawTx)
+          services.addServiceCallSuccess(stc, `not found`)
         else
           services.addServiceCallFailure(stc)
 

package/src/storage/StorageKnex.ts

@@ -23,12 +23,13 @@ import {
 } from './schema/tables'
 import { KnexMigrations } from './schema/KnexMigrations'
 import { Knex } from 'knex'
-import { StorageAdminStats, StorageProvider, StorageProviderOptions } from './StorageProvider'
+import { AdminStatsResult, StorageProvider, StorageProviderOptions } from './StorageProvider'
 import { purgeData } from './methods/purgeData'
 import { listActions } from './methods/listActionsKnex'
 import { listOutputs } from './methods/listOutputsKnex'
 import { DBType } from './StorageReader'
 import { reviewStatus } from './methods/reviewStatus'
+import { ServicesCallHistory } from '../sdk/WalletServices.interfaces'
 
 export interface StorageKnexOptions extends StorageProviderOptions {
   /**
@@ -1152,9 +1153,13 @@ export class StorageKnex extends StorageProvider implements sdk.WalletStoragePro
     return entities
   }
 
-  async adminStats(adminIdentityKey: string): Promise<StorageAdminStats> {
+  async adminStats(adminIdentityKey: string): Promise<AdminStatsResult> {
     if (this.dbtype !== 'MySQL') throw new sdk.WERR_NOT_IMPLEMENTED('adminStats, only MySQL is supported')
 
+    const monitorEvent = verifyOneOrNone(await this.findMonitorEvents({ partial: { event: 'ServiceCallHistory'}, orderDescending: true, paged: { limit: 1 } }))
+    const monitorStats: ServicesCallHistory | undefined = monitorEvent ? JSON.parse(monitorEvent.details!) : undefined
+    const servicesStats = this.getServices().getServicesCallHistory(true)
+
     const one_day_ago = new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString()
     const one_week_ago = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString()
     const one_month_ago = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString()
@@ -1295,7 +1300,9 @@ select
     (select count(*) from output_tags where created_at > '${one_month_ago}') as tagsMonth,
 	  (select count(*) from output_tags) as tagsTotal
       `)
-    const r: StorageAdminStats = {
+    const r: AdminStatsResult = {
+      monitorStats,
+      servicesStats,
       requestedBy: adminIdentityKey,
       when: new Date().toISOString(),
       usersDay,

package/src/storage/StorageProvider.ts

@@ -40,6 +40,7 @@ import { createAction } from './methods/createAction'
 import { internalizeAction } from './methods/internalizeAction'
 import { StorageReaderWriter, StorageReaderWriterOptions } from './StorageReaderWriter'
 import { EntityProvenTx, EntityProvenTxReq, EntitySyncState, EntityTransaction } from './schema/entities'
+import { ServicesCallHistory } from '../sdk/WalletServices.interfaces'
 
 export abstract class StorageProvider extends StorageReaderWriter implements sdk.WalletStorageProvider {
   isDirty = false
@@ -106,7 +107,7 @@ export abstract class StorageProvider extends StorageReaderWriter implements sdk
   abstract findOutputsAuth(auth: sdk.AuthId, args: sdk.FindOutputsArgs): Promise<TableOutput[]>
   abstract insertCertificateAuth(auth: sdk.AuthId, certificate: TableCertificateX): Promise<number>
 
-  abstract adminStats(adminIdentityKey: string): Promise<StorageAdminStats>
+  abstract adminStats(adminIdentityKey: string): Promise<AdminStatsResult>
 
   override isStorageProvider(): boolean {
     return true
@@ -773,3 +774,8 @@ export interface StorageAdminStats {
   tagsMonth: number
   tagsTotal: number
 }
+
+export interface AdminStatsResult extends StorageAdminStats {
+  servicesStats?: ServicesCallHistory
+  monitorStats?: ServicesCallHistory
+}

package/src/storage/schema/entities/__tests/ProvenTxTests.test.ts

@@ -136,7 +136,18 @@ describe('ProvenTx class method tests', () => {
       }),
       nLockTimeIsFinal: async () => true,
 
-      getBeefForTxid: async () => new bsv.Beef()
+      getBeefForTxid: async () => new bsv.Beef(),
+
+      getServicesCallHistory: () => ({
+        version: 1,
+        getMerklePath: { serviceName: '', historyByProvider: {} },
+        getRawTx: { serviceName: '', historyByProvider: {} },
+        postBeef: { serviceName: '', historyByProvider: {} },
+        getStatusForTxids: { serviceName: '', historyByProvider: {} },
+        getUtxoStatus: { serviceName: '', historyByProvider: {} },
+        getScriptHashHistory: { serviceName: '', historyByProvider: {} },
+        updateFiatExchangeRates: { serviceName: '', historyByProvider: {} }
+      })
     }
 
     // Call the method under test

package/test/Wallet/local/localWallet.man.test.ts

@@ -1,5 +1,5 @@
 import { EntitySyncState, sdk } from '../../../src'
-import { _tu } from '../../utils/TestUtilsWalletStorage'
+import { _tu, logger } from '../../utils/TestUtilsWalletStorage'
 import { specOpInvalidChange } from '../../../src/sdk'
 import { createOneSatTestOutput, createSetup, LocalWalletTestOptions } from '../../utils/localWalletMethods'
 
@@ -32,9 +32,10 @@ describe('localWallet tests', () => {
     expect(key.publicKey.toString()).toBe(setup.identityKey)
     await setup.services.getRawTx('6dd8e416dfaf14c04899ccad2bf76a67c1d5598fece25cf4dcb7a076012b7d8d')
     await setup.services.getRawTx('ac9cced61e2491be55061ce6577e0c59b909922ba92d5cc1cd754b10d721ab0e')
+    await setup.monitor.runOnce()
     await setup.services.getRawTx('0000e416dfaf14c04899ccad2bf76a67c1d5598fece25cf4dcb7a076012b7d8d')
     await setup.services.getRawTx('0000ced61e2491be55061ce6577e0c59b909922ba92d5cc1cd754b10d721ab0e')
-    await setup.monitor.runOnce()
+    logger(await setup.monitor.runTask('ServiceCallHistory'))
     await setup.wallet.destroy()
   })