@bsv/wallet-toolbox 1.5.20 → 1.6.1

package/src/monitor/Monitor.ts

@@ -1,7 +1,4 @@
-import * as sdk from '../sdk'
-import { Services } from '../services'
 import { wait } from '../utility/utilityHelpers'
-import { BlockHeader, ChaintracksServiceClient } from '../services/chaintracker'
 
 import { WalletMonitorTask } from './tasks/WalletMonitorTask'
 import { WalletStorageManager } from '../storage/WalletStorageManager'
@@ -18,11 +15,18 @@ import { TaskMonitorCallHistory } from './tasks/TaskMonitorCallHistory'
 import { TaskSendWaiting } from './tasks/TaskSendWaiting'
 import { TaskCheckNoSends } from './tasks/TaskCheckNoSends'
 import { TaskUnFail } from './tasks/TaskUnFail'
+import { Chain, ProvenTransactionStatus } from '../sdk/types'
+import { ChaintracksServiceClient } from '../services/chaintracker/chaintracks/ChaintracksServiceClient'
+import { ReviewActionResult } from '../sdk/WalletStorage.interfaces'
+import { WERR_BAD_REQUEST, WERR_INVALID_PARAMETER } from '../sdk/WERR_errors'
+import { WalletError } from '../sdk/WalletError'
+import { BlockHeader } from '../sdk/WalletServices.interfaces'
+import { Services } from '../services/Services'
 
 export type MonitorStorage = WalletStorageManager
 
 export interface MonitorOptions {
-  chain: sdk.Chain
+  chain: Chain
 
   services: Services
 
@@ -46,8 +50,8 @@ export interface MonitorOptions {
   /**
    * These are hooks for a wallet-toolbox client to get transaction updates.
    */
-  onTransactionBroadcasted?: (broadcastResult: sdk.ReviewActionResult) => Promise<void>
-  onTransactionProven?: (txStatus: sdk.ProvenTransactionStatus) => Promise<void>
+  onTransactionBroadcasted?: (broadcastResult: ReviewActionResult) => Promise<void>
+  onTransactionProven?: (txStatus: ProvenTransactionStatus) => Promise<void>
 }
 
 /**
@@ -55,13 +59,9 @@ export interface MonitorOptions {
  * and potentially that reorgs update proofs that were already received.
  */
 export class Monitor {
-  static createDefaultWalletMonitorOptions(
-    chain: sdk.Chain,
-    storage: MonitorStorage,
-    services?: Services
-  ): MonitorOptions {
+  static createDefaultWalletMonitorOptions(chain: Chain, storage: MonitorStorage, services?: Services): MonitorOptions {
     services ||= new Services(chain)
-    if (!services.options.chaintracks) throw new sdk.WERR_INVALID_PARAMETER('services.options.chaintracks', 'valid')
+    if (!services.options.chaintracks) throw new WERR_INVALID_PARAMETER('services.options.chaintracks', 'valid')
     const o: MonitorOptions = {
       chain,
       services,
@@ -78,11 +78,11 @@ export class Monitor {
 
   options: MonitorOptions
   services: Services
-  chain: sdk.Chain
+  chain: Chain
   storage: MonitorStorage
   chaintracks: ChaintracksServiceClient
-  onTransactionBroadcasted?: (broadcastResult: sdk.ReviewActionResult) => Promise<void>
-  onTransactionProven?: (txStatus: sdk.ProvenTransactionStatus) => Promise<void>
+  onTransactionBroadcasted?: (broadcastResult: ReviewActionResult) => Promise<void>
+  onTransactionProven?: (txStatus: ProvenTransactionStatus) => Promise<void>
 
   constructor(options: MonitorOptions) {
     this.options = { ...options }
@@ -169,7 +169,7 @@ export class Monitor {
 
   addTask(task: WalletMonitorTask): void {
     if (this._tasks.some(t => t.name === task.name))
-      throw new sdk.WERR_BAD_REQUEST(`task ${task.name} has already been added.`)
+      throw new WERR_BAD_REQUEST(`task ${task.name} has already been added.`)
     this._tasks.push(task)
   }
 
@@ -202,7 +202,7 @@ export class Monitor {
         try {
           await t.asyncSetup()
         } catch (eu: unknown) {
-          const e = sdk.WalletError.fromUnknown(eu)
+          const e = WalletError.fromUnknown(eu)
           const details = `monitor task ${t.name} asyncSetup error ${e.code} ${e.description}`
           console.log(details)
           await this.logEvent('error0', details)
@@ -219,7 +219,7 @@ export class Monitor {
         try {
           if (t.trigger(now).run) tasksToRun.push(t)
         } catch (eu: unknown) {
-          const e = sdk.WalletError.fromUnknown(eu)
+          const e = WalletError.fromUnknown(eu)
           const details = `monitor task ${t.name} trigger error ${e.code} ${e.description}`
           console.log(details)
           await this.logEvent('error0', details)
@@ -236,7 +236,7 @@ export class Monitor {
             }
           }
         } catch (eu: unknown) {
-          const e = sdk.WalletError.fromUnknown(eu)
+          const e = WalletError.fromUnknown(eu)
           const details = `monitor task ${ttr.name} runTask error ${e.code} ${e.description}\n${e.stack}`
           console.log(details)
           await this.logEvent('error1', details)
@@ -250,7 +250,7 @@ export class Monitor {
   _runAsyncSetup: boolean = true
 
   async startTasks(): Promise<void> {
-    if (this._tasksRunning) throw new sdk.WERR_BAD_REQUEST('monitor tasks are already runnining.')
+    if (this._tasksRunning) throw new WERR_BAD_REQUEST('monitor tasks are already runnining.')
 
     this._tasksRunning = true
     for (; this._tasksRunning; ) {
@@ -291,7 +291,7 @@ export class Monitor {
     const h = header
     this.lastNewHeader = h
     this.lastNewHeaderWhen = new Date()
-    console.log(`WalletMonitor notified of new block header ${h.height}`)
+    // console.log(`WalletMonitor notified of new block header ${h.height}`)
     // Nudge the proof checker to try again.
     TaskCheckForProofs.checkNow = true
   }
@@ -303,7 +303,7 @@ export class Monitor {
    *
    * @param broadcastResult
    */
-  callOnBroadcastedTransaction(broadcastResult: sdk.ReviewActionResult): void {
+  callOnBroadcastedTransaction(broadcastResult: ReviewActionResult): void {
     if (this.onTransactionBroadcasted) {
       this.onTransactionBroadcasted(broadcastResult)
     }
@@ -316,7 +316,7 @@ export class Monitor {
    *
    * @param txStatus
    */
-  callOnProvenTransaction(txStatus: sdk.ProvenTransactionStatus): void {
+  callOnProvenTransaction(txStatus: ProvenTransactionStatus): void {
     if (this.onTransactionProven) {
       this.onTransactionProven(txStatus)
     }

package/src/monitor/MonitorDaemon.ts

@@ -1,27 +1,23 @@
-import {
-  Monitor,
-  sdk,
-  Services,
-  StorageKnex,
-  StorageKnexOptions,
-  StorageProvider,
-  wait,
-  WalletStorageManager
-} from '../index.all'
-
-// This task is not "client" compatible as it imports StorageKnex
-import { TaskUnFail } from './tasks/TaskUnFail'
-
 import { Knex, knex as makeKnex } from 'knex'
 
 import dotenv from 'dotenv'
+import { Chain } from '../sdk/types'
+import { StorageKnex, StorageKnexOptions } from '../storage/StorageKnex'
+import { StorageProvider } from '../storage/StorageProvider'
+import { WalletStorageManager } from '../storage/WalletStorageManager'
+import { WalletServicesOptions } from '../sdk/WalletServices.interfaces'
+import { Services } from '../services/Services'
+import { Monitor } from './Monitor'
+import { WERR_INTERNAL, WERR_INVALID_PARAMETER } from '../sdk/WERR_errors'
+import { wait } from '../utility/utilityHelpers'
+import { WalletError } from '../sdk/WalletError'
 dotenv.config()
 
 const mainDojoConnection = process.env.MAIN_DOJO_CONNECTION || ''
 const testDojoConnection = process.env.TEST_DOJO_CONNECTION || ''
 
 export interface MonitorDaemonSetup {
-  chain?: sdk.Chain
+  chain?: Chain
   sqliteFilename?: string
   mySQLConnection?: string
   knexConfig?: Knex.Config
@@ -29,7 +25,7 @@ export interface MonitorDaemonSetup {
   storageKnexOptions?: StorageKnexOptions
   storageProvider?: StorageProvider
   storageManager?: WalletStorageManager
-  servicesOptions?: sdk.WalletServicesOptions
+  servicesOptions?: WalletServicesOptions
   services?: Services
   monitor?: Monitor
 }
@@ -94,7 +90,7 @@ export class MonitorDaemon {
         a.storageManager = new WalletStorageManager(settings.storageIdentityKey, a.storageProvider)
         await a.storageManager.makeAvailable()
       } else if (!a.storageManager) {
-        throw new sdk.WERR_INVALID_PARAMETER(
+        throw new WERR_INVALID_PARAMETER(
           'storageManager',
           'valid or one of mySQLConnection, knexConfig, knex, storageKnexOptions, or storageProvider'
         )
@@ -102,7 +98,7 @@ export class MonitorDaemon {
 
       if (a.servicesOptions) {
         if (a.servicesOptions.chain != a.chain)
-          throw new sdk.WERR_INVALID_PARAMETER('serviceOptions.chain', 'same as args.chain')
+          throw new WERR_INVALID_PARAMETER('serviceOptions.chain', 'same as args.chain')
         a.services = new Services(a.servicesOptions)
       }
 
@@ -123,7 +119,7 @@ export class MonitorDaemon {
 
   async start(): Promise<void> {
     if (!this.setup) await this.createSetup()
-    if (!this.setup?.monitor) throw new sdk.WERR_INTERNAL('createSetup failed to initialize setup')
+    if (!this.setup?.monitor) throw new WERR_INTERNAL('createSetup failed to initialize setup')
 
     const { monitor } = this.setup
 
@@ -137,7 +133,7 @@ export class MonitorDaemon {
     console.log('start of stop')
 
     if (!this.setup || (!this.doneTasks && !this.noRunTasks) || !this.doneListening)
-      throw new sdk.WERR_INTERNAL('call start or createSetup first')
+      throw new WERR_INTERNAL('call start or createSetup first')
 
     const { monitor } = this.setup
 
@@ -176,7 +172,7 @@ export class MonitorDaemon {
 
         console.log('done')
       } catch (eu: unknown) {
-        const e = sdk.WalletError.fromUnknown(eu)
+        const e = WalletError.fromUnknown(eu)
         console.log(`\n\nrunWatchman Main Error Handler\n\ncode: ${e.code}\nDescription: ${e.description}\n\n\n`)
       }
     }

package/src/monitor/tasks/TaskCheckForProofs.ts

@@ -39,9 +39,9 @@ export class TaskCheckForProofs extends WalletMonitorTask {
    */
   trigger(nowMsecsSinceEpoch: number): { run: boolean } {
     return {
-      run:
-        TaskCheckForProofs.checkNow ||
-        (this.triggerMsecs > 0 && nowMsecsSinceEpoch - this.lastRunMsecsSinceEpoch > this.triggerMsecs)
+      run: TaskCheckForProofs.checkNow
+      // Check only when checkNow flag is set.
+      // || (this.triggerMsecs > 0 && nowMsecsSinceEpoch - this.lastRunMsecsSinceEpoch > this.triggerMsecs)
     }
   }
 

package/src/monitor/tasks/TaskNewHeader.ts

@@ -1,4 +1,4 @@
-import { BlockHeader } from '../../services/chaintracker/chaintracks/Api/BlockHeaderApi'
+import { BlockHeader } from '../../sdk/WalletServices.interfaces'
 import { Monitor } from '../Monitor'
 import { WalletMonitorTask } from './WalletMonitorTask'
 
@@ -25,6 +25,7 @@ export class TaskNewHeader extends WalletMonitorTask {
    * when a cycle without a new header occurs and `processNewBlockHeader` is called.
    */
   queuedHeader?: BlockHeader
+  queuedHeaderWhen?: Date
 
   constructor(
     monitor: Monitor,
@@ -37,6 +38,21 @@ export class TaskNewHeader extends WalletMonitorTask {
     return await this.monitor.chaintracks.findChainTipHeader()
   }
 
+  /**
+   * TODO: This is a temporary incomplete solution for which a full chaintracker
+   * with new header and reorg event notification is required.
+   *
+   * New header events drive retrieving merklePaths for newly mined transactions.
+   * This implementation performs this function.
+   *
+   * Reorg events are needed to know when previously retrieved mekrlePaths need to be
+   * updated in the proven_txs table (and ideally notifications delivered to users).
+   * Note that in-general, a reorg only shifts where in the block a transaction is mined,
+   * and sometimes which block. In the case of coinbase transactions, a transaction may
+   * also fail after a reorg.
+   */
+  override async asyncSetup(): Promise<void> {}
+
   trigger(nowMsecsSinceEpoch: number): { run: boolean } {
     const run = true
     return { run }
@@ -49,6 +65,10 @@ export class TaskNewHeader extends WalletMonitorTask {
     let isNew = true
     if (!oldHeader) {
       log = `first header: ${this.header.height} ${this.header.hash}`
+    } else if (oldHeader.height > this.header.height) {
+      log = `old header: ${this.header.height} vs ${oldHeader.height}`
+      this.header = oldHeader // Revert to old header with the higher height
+      isNew = false
     } else if (oldHeader.height < this.header.height) {
       const skip = this.header.height - oldHeader.height - 1
       const skipped = skip > 0 ? ` SKIPPED ${skip}` : ''
@@ -60,9 +80,11 @@ export class TaskNewHeader extends WalletMonitorTask {
     }
     if (isNew) {
       this.queuedHeader = this.header
+      this.queuedHeaderWhen = new Date()
     } else if (this.queuedHeader) {
       // Only process new block header if it has remained the chain tip for a full cycle
-      log = `process header: ${this.header.height} ${this.header.hash}`
+      const delay = (new Date().getTime() - this.queuedHeaderWhen!.getTime()) / 1000 // seconds
+      log = `process header: ${this.header.height} ${this.header.hash} delayed ${delay.toFixed(1)} secs`
       this.monitor.processNewBlockHeader(this.queuedHeader)
       this.queuedHeader = undefined
     }

package/src/monitor/tasks/TaskSendWaiting.ts

@@ -1,11 +1,12 @@
-import { EntityProvenTxReq, TableProvenTxReq } from '../../storage/index.client'
-import { verifyTruthy } from '../../utility/index.client'
+import { ReviewActionResult, SendWithResult } from '@bsv/sdk'
 import { Monitor } from '../Monitor'
 import { WalletMonitorTask } from './WalletMonitorTask'
 import { attemptToPostReqsToNetwork } from '../../storage/methods/attemptToPostReqsToNetwork'
-import { ProvenTxReqStatus, WERR_INTERNAL } from '../../sdk'
-import { ReviewActionResult, SendWithResult } from '@bsv/sdk'
 import { aggregateActionResults } from '../../utility/aggregateResults'
+import { ProvenTxReqStatus } from '../../sdk/types'
+import { verifyTruthy } from '../../utility/utilityHelpers'
+import { TableProvenTxReq } from '../../storage/schema/tables/TableProvenTxReq'
+import { EntityProvenTxReq } from '../../storage/schema/entities/EntityProvenTxReq'
 
 export class TaskSendWaiting extends WalletMonitorTask {
   static taskName = 'SendWaiting'

package/src/sdk/WalletServices.interfaces.ts

@@ -1,8 +1,8 @@
 import { ArcConfig, Beef, Transaction as BsvTransaction, ChainTracker, MerklePath } from '@bsv/sdk'
-import { ChaintracksServiceClient } from '../services/chaintracker'
 import { Chain, ReqHistoryNote } from './types'
 import { WalletError } from './WalletError'
 import { TableOutput } from '../storage/schema/tables/TableOutput'
+import { ChaintracksServiceClient } from '../services/chaintracker/chaintracks/ChaintracksServiceClient'
 /**
  * Defines standard interfaces to access functionality implemented by external transaction processing services.
  */

package/src/sdk/validationHelpers.ts

@@ -44,8 +44,8 @@ import {
   Utils,
   WalletPayment
 } from '@bsv/sdk'
-import { sdk } from '../index.client'
 import { OutPoint } from './types'
+import { WERR_INTERNAL, WERR_INVALID_PARAMETER } from './WERR_errors'
 
 export function parseWalletOutpoint(outpoint: string): {
   txid: string
@@ -86,8 +86,8 @@ function validateOptionalStringLength(
 
 export function validateSatoshis(v: number | undefined, name: string, min?: number): number {
   if (v === undefined || !Number.isInteger(v) || v < 0 || v > 21e14)
-    throw new sdk.WERR_INVALID_PARAMETER(name, 'a valid number of satoshis')
-  if (min !== undefined && v < min) throw new sdk.WERR_INVALID_PARAMETER(name, `at least ${min} satoshis.`)
+    throw new WERR_INVALID_PARAMETER(name, 'a valid number of satoshis')
+  if (min !== undefined && v < min) throw new WERR_INVALID_PARAMETER(name, `at least ${min} satoshis.`)
   return v
 }
 
@@ -110,12 +110,12 @@ export function validateInteger(
 ): number {
   if (v === undefined) {
     if (defaultValue !== undefined) return defaultValue
-    throw new sdk.WERR_INVALID_PARAMETER(name, 'a valid integer')
+    throw new WERR_INVALID_PARAMETER(name, 'a valid integer')
   }
-  if (!Number.isInteger(v)) throw new sdk.WERR_INVALID_PARAMETER(name, 'an integer')
+  if (!Number.isInteger(v)) throw new WERR_INVALID_PARAMETER(name, 'an integer')
   v = Number(v)
-  if (min !== undefined && v < min) throw new sdk.WERR_INVALID_PARAMETER(name, `at least ${min} length.`)
-  if (max !== undefined && v > max) throw new sdk.WERR_INVALID_PARAMETER(name, `no more than ${max} length.`)
+  if (min !== undefined && v < min) throw new WERR_INVALID_PARAMETER(name, `at least ${min} length.`)
+  if (max !== undefined && v > max) throw new WERR_INVALID_PARAMETER(name, `no more than ${max} length.`)
   return v
 }
 
@@ -125,8 +125,8 @@ export function validatePositiveIntegerOrZero(v: number, name: string): number {
 
 export function validateStringLength(s: string, name: string, min?: number, max?: number): string {
   const bytes = Utils.toArray(s, 'utf8').length
-  if (min !== undefined && bytes < min) throw new sdk.WERR_INVALID_PARAMETER(name, `at least ${min} length.`)
-  if (max !== undefined && bytes > max) throw new sdk.WERR_INVALID_PARAMETER(name, `no more than ${max} length.`)
+  if (min !== undefined && bytes < min) throw new WERR_INVALID_PARAMETER(name, `at least ${min} length.`)
+  if (max !== undefined && bytes > max) throw new WERR_INVALID_PARAMETER(name, `no more than ${max} length.`)
   return s
 }
 
@@ -150,8 +150,8 @@ function validateTag(s: string): string {
 function validateIdentifier(s: string, name: string, min?: number, max?: number): string {
   s = s.trim().toLowerCase()
   const bytes = Utils.toArray(s, 'utf8').length
-  if (min !== undefined && bytes < min) throw new sdk.WERR_INVALID_PARAMETER(name, `at least ${min} length.`)
-  if (max !== undefined && bytes > max) throw new sdk.WERR_INVALID_PARAMETER(name, `no more than ${max} length.`)
+  if (min !== undefined && bytes < min) throw new WERR_INVALID_PARAMETER(name, `at least ${min} length.`)
+  if (max !== undefined && bytes > max) throw new WERR_INVALID_PARAMETER(name, `no more than ${max} length.`)
   return s
 }
 
@@ -173,12 +173,12 @@ function validateBase64String(s: string, name: string, min?: number, max?: numbe
   const paddingCount = paddingMatch ? paddingMatch[0].length : 0
 
   if (paddingCount > 2 || (s.length % 4 !== 0 && paddingCount !== 0) || !base64Regex.test(s)) {
-    throw new sdk.WERR_INVALID_PARAMETER(name, `balid base64 string`)
+    throw new WERR_INVALID_PARAMETER(name, `balid base64 string`)
   }
 
   const bytes = Utils.toArray(s, 'base64').length
-  if (min !== undefined && bytes < min) throw new sdk.WERR_INVALID_PARAMETER(name, `at least ${min} length.`)
-  if (max !== undefined && bytes > max) throw new sdk.WERR_INVALID_PARAMETER(name, `no more than ${max} length.`)
+  if (min !== undefined && bytes < min) throw new WERR_INVALID_PARAMETER(name, `at least ${min} length.`)
+  if (max !== undefined && bytes > max) throw new WERR_INVALID_PARAMETER(name, `no more than ${max} length.`)
 
   return s
 }
@@ -202,11 +202,11 @@ function validateOptionalHexString(
  */
 function validateHexString(s: string, name: string, min?: number, max?: number): string {
   s = s.trim().toLowerCase()
-  if (s.length % 2 === 1) throw new sdk.WERR_INVALID_PARAMETER(name, `even length, not ${s.length}.`)
+  if (s.length % 2 === 1) throw new WERR_INVALID_PARAMETER(name, `even length, not ${s.length}.`)
   const hexRegex = /^[0-9A-Fa-f]+$/
-  if (!hexRegex.test(s)) throw new sdk.WERR_INVALID_PARAMETER(name, `hexadecimal string.`)
-  if (min !== undefined && s.length < min) throw new sdk.WERR_INVALID_PARAMETER(name, `at least ${min} length.`)
-  if (max !== undefined && s.length > max) throw new sdk.WERR_INVALID_PARAMETER(name, `no more than ${max} length.`)
+  if (!hexRegex.test(s)) throw new WERR_INVALID_PARAMETER(name, `hexadecimal string.`)
+  if (min !== undefined && s.length < min) throw new WERR_INVALID_PARAMETER(name, `at least ${min} length.`)
+  if (max !== undefined && s.length > max) throw new WERR_INVALID_PARAMETER(name, `no more than ${max} length.`)
   return s
 }
 
@@ -236,11 +236,11 @@ export interface ValidCreateActionInput {
 
 export function validateCreateActionInput(i: CreateActionInput): ValidCreateActionInput {
   if (i.unlockingScript === undefined && i.unlockingScriptLength === undefined)
-    throw new sdk.WERR_INVALID_PARAMETER('unlockingScript, unlockingScriptLength', `at least one valid value.`)
+    throw new WERR_INVALID_PARAMETER('unlockingScript, unlockingScriptLength', `at least one valid value.`)
   const unlockingScript = validateOptionalHexString(i.unlockingScript, 'unlockingScript')
   const unlockingScriptLength = i.unlockingScriptLength ?? unlockingScript!.length / 2
   if (unlockingScript && unlockingScriptLength !== unlockingScript.length / 2)
-    throw new sdk.WERR_INVALID_PARAMETER('unlockingScriptLength', `length unlockingScript if both valid.`)
+    throw new WERR_INVALID_PARAMETER('unlockingScriptLength', `length unlockingScript if both valid.`)
   const vi: ValidCreateActionInput = {
     outpoint: parseWalletOutpoint(i.outpoint),
     inputDescription: validateStringLength(i.inputDescription, 'inputDescription', 5, 2000),
@@ -316,7 +316,7 @@ export interface ValidSignActionOptions extends ValidProcessActionOptions {
 }
 
 export interface ValidProcessActionArgs extends ValidWalletSignerArgs {
-  options: sdk.ValidProcessActionOptions
+  options: ValidProcessActionOptions
   // true if a batch of transactions is included for processing.
   isSendWith: boolean
   // true if there is a new transaction (not no inputs and no outputs)
@@ -332,8 +332,8 @@ export interface ValidProcessActionArgs extends ValidWalletSignerArgs {
 export interface ValidCreateActionArgs extends ValidProcessActionArgs {
   description: DescriptionString5to2000Bytes
   inputBEEF?: BEEF
-  inputs: sdk.ValidCreateActionInput[]
-  outputs: sdk.ValidCreateActionOutput[]
+  inputs: ValidCreateActionInput[]
+  outputs: ValidCreateActionOutput[]
   lockTime: number
   version: number
   labels: string[]
@@ -354,7 +354,7 @@ export interface ValidSignActionArgs extends ValidProcessActionArgs {
   spends: Record<PositiveIntegerOrZero, SignActionSpend>
   reference: Base64String
 
-  options: sdk.ValidSignActionOptions
+  options: ValidSignActionOptions
 }
 
 export function validateCreateActionArgs(args: CreateActionArgs): ValidCreateActionArgs {
@@ -475,7 +475,7 @@ export interface ValidInternalizeOutput {
 
 export function validateInternalizeOutput(args: InternalizeOutput): ValidInternalizeOutput {
   if (args.protocol !== 'basket insertion' && args.protocol !== 'wallet payment')
-    throw new sdk.WERR_INVALID_PARAMETER('protocol', `'basket insertion' or 'wallet payment'`)
+    throw new WERR_INVALID_PARAMETER('protocol', `'basket insertion' or 'wallet payment'`)
   const v: ValidInternalizeOutput = {
     outputIndex: validatePositiveIntegerOrZero(args.outputIndex, 'outputIndex'),
     protocol: args.protocol,
@@ -515,12 +515,12 @@ export function validateInternalizeActionArgs(args: InternalizeActionArgs): Vali
   try {
     const beef = Beef.fromBinary(vargs.tx)
     if (beef.txs.length < 1)
-      throw new sdk.WERR_INVALID_PARAMETER('tx', `at least one transaction to internalize an output from`)
+      throw new WERR_INVALID_PARAMETER('tx', `at least one transaction to internalize an output from`)
   } catch {
-    throw new sdk.WERR_INVALID_PARAMETER('tx', `valid with at least one transaction to internalize an output from`)
+    throw new WERR_INVALID_PARAMETER('tx', `valid with at least one transaction to internalize an output from`)
   }
   if (vargs.outputs.length < 1)
-    throw new sdk.WERR_INVALID_PARAMETER('outputs', `at least one output to internalize from the transaction`)
+    throw new WERR_INVALID_PARAMETER('outputs', `at least one output to internalize from the transaction`)
 
   return vargs
 }
@@ -533,7 +533,7 @@ export function validateOptionalOutpointString(outpoint: string | undefined, nam
 export function validateOutpointString(outpoint: string, name: string): string {
   const s = outpoint.split('.')
   if (s.length !== 2 || !Number.isInteger(Number(s[1])))
-    throw new sdk.WERR_INVALID_PARAMETER(name, `txid as hex string and numeric output index joined with '.'`)
+    throw new WERR_INVALID_PARAMETER(name, `txid as hex string and numeric output index joined with '.'`)
   const txid = validateHexString(s[0], `${name} txid`, undefined, 64)
   const vout = validatePositiveIntegerOrZero(Number(s[1]), `${name} vout`)
   return `${txid}.${vout}`
@@ -680,14 +680,13 @@ export async function validateAcquireCertificateArgs(
     privilegedReason: validateOptionalStringLength(args.privilegedReason, 'privilegedReason', 5, 50)
   }
   if (vargs.privileged && !vargs.privilegedReason)
-    throw new sdk.WERR_INVALID_PARAMETER('privilegedReason', `valid when 'privileged' is true `)
+    throw new WERR_INVALID_PARAMETER('privilegedReason', `valid when 'privileged' is true `)
   if (vargs.acquisitionProtocol === 'direct') {
     if (!vargs.serialNumber)
-      throw new sdk.WERR_INVALID_PARAMETER('serialNumber', 'valid when acquisitionProtocol is "direct"')
-    if (!vargs.signature)
-      throw new sdk.WERR_INVALID_PARAMETER('signature', 'valid when acquisitionProtocol is "direct"')
+      throw new WERR_INVALID_PARAMETER('serialNumber', 'valid when acquisitionProtocol is "direct"')
+    if (!vargs.signature) throw new WERR_INVALID_PARAMETER('signature', 'valid when acquisitionProtocol is "direct"')
     if (!vargs.revocationOutpoint)
-      throw new sdk.WERR_INVALID_PARAMETER('revocationOutpoint', 'valid when acquisitionProtocol is "direct"')
+      throw new WERR_INVALID_PARAMETER('revocationOutpoint', 'valid when acquisitionProtocol is "direct"')
   }
   return vargs
 }
@@ -733,20 +732,19 @@ export function validateAcquireIssuanceCertificateArgs(
   args: AcquireCertificateArgs
 ): ValidAcquireIssuanceCertificateArgs {
   if (args.acquisitionProtocol !== 'issuance')
-    throw new sdk.WERR_INTERNAL('Only acquire certificate via issuance requests allowed here.')
-  if (args.serialNumber)
-    throw new sdk.WERR_INVALID_PARAMETER('serialNumber', 'valid when acquisitionProtocol is "direct"')
-  if (args.signature) throw new sdk.WERR_INVALID_PARAMETER('signature', 'valid when acquisitionProtocol is "direct"')
+    throw new WERR_INTERNAL('Only acquire certificate via issuance requests allowed here.')
+  if (args.serialNumber) throw new WERR_INVALID_PARAMETER('serialNumber', 'valid when acquisitionProtocol is "direct"')
+  if (args.signature) throw new WERR_INVALID_PARAMETER('signature', 'valid when acquisitionProtocol is "direct"')
   if (args.revocationOutpoint)
-    throw new sdk.WERR_INVALID_PARAMETER('revocationOutpoint', 'valid when acquisitionProtocol is "direct"')
+    throw new WERR_INVALID_PARAMETER('revocationOutpoint', 'valid when acquisitionProtocol is "direct"')
   if (args.keyringRevealer)
-    throw new sdk.WERR_INVALID_PARAMETER('keyringRevealer', 'valid when acquisitionProtocol is "direct"')
+    throw new WERR_INVALID_PARAMETER('keyringRevealer', 'valid when acquisitionProtocol is "direct"')
   if (args.keyringForSubject)
-    throw new sdk.WERR_INVALID_PARAMETER('keyringForSubject', 'valid when acquisitionProtocol is "direct"')
+    throw new WERR_INVALID_PARAMETER('keyringForSubject', 'valid when acquisitionProtocol is "direct"')
   if (!args.certifierUrl)
-    throw new sdk.WERR_INVALID_PARAMETER('certifierUrl', 'valid when acquisitionProtocol is "issuance"')
+    throw new WERR_INVALID_PARAMETER('certifierUrl', 'valid when acquisitionProtocol is "issuance"')
   if (args.privileged && !args.privilegedReason)
-    throw new sdk.WERR_INVALID_PARAMETER('privilegedReason', `valid when 'privileged' is true `)
+    throw new WERR_INVALID_PARAMETER('privilegedReason', `valid when 'privileged' is true `)
 
   const vargs: ValidAcquireIssuanceCertificateArgs = {
     type: validateBase64String(args.type, 'type'),
@@ -761,18 +759,17 @@ export function validateAcquireIssuanceCertificateArgs(
 }
 export function validateAcquireDirectCertificateArgs(args: AcquireCertificateArgs): ValidAcquireDirectCertificateArgs {
   if (args.acquisitionProtocol !== 'direct')
-    throw new sdk.WERR_INTERNAL('Only acquire direct certificate requests allowed here.')
-  if (!args.serialNumber)
-    throw new sdk.WERR_INVALID_PARAMETER('serialNumber', 'valid when acquisitionProtocol is "direct"')
-  if (!args.signature) throw new sdk.WERR_INVALID_PARAMETER('signature', 'valid when acquisitionProtocol is "direct"')
+    throw new WERR_INTERNAL('Only acquire direct certificate requests allowed here.')
+  if (!args.serialNumber) throw new WERR_INVALID_PARAMETER('serialNumber', 'valid when acquisitionProtocol is "direct"')
+  if (!args.signature) throw new WERR_INVALID_PARAMETER('signature', 'valid when acquisitionProtocol is "direct"')
   if (!args.revocationOutpoint)
-    throw new sdk.WERR_INVALID_PARAMETER('revocationOutpoint', 'valid when acquisitionProtocol is "direct"')
+    throw new WERR_INVALID_PARAMETER('revocationOutpoint', 'valid when acquisitionProtocol is "direct"')
   if (!args.keyringRevealer)
-    throw new sdk.WERR_INVALID_PARAMETER('keyringRevealer', 'valid when acquisitionProtocol is "direct"')
+    throw new WERR_INVALID_PARAMETER('keyringRevealer', 'valid when acquisitionProtocol is "direct"')
   if (!args.keyringForSubject)
-    throw new sdk.WERR_INVALID_PARAMETER('keyringForSubject', 'valid when acquisitionProtocol is "direct"')
+    throw new WERR_INVALID_PARAMETER('keyringForSubject', 'valid when acquisitionProtocol is "direct"')
   if (args.privileged && !args.privilegedReason)
-    throw new sdk.WERR_INVALID_PARAMETER('privilegedReason', `valid when 'privileged' is true `)
+    throw new WERR_INVALID_PARAMETER('privilegedReason', `valid when 'privileged' is true `)
 
   const vargs: ValidAcquireDirectCertificateArgs = {
     type: validateBase64String(args.type, 'type'),
@@ -806,7 +803,7 @@ export interface ValidProveCertificateArgs extends ValidWalletSignerArgs {
 
 export function validateProveCertificateArgs(args: ProveCertificateArgs): ValidProveCertificateArgs {
   if (args.privileged && !args.privilegedReason)
-    throw new sdk.WERR_INVALID_PARAMETER('privilegedReason', `valid when 'privileged' is true `)
+    throw new WERR_INVALID_PARAMETER('privilegedReason', `valid when 'privileged' is true `)
 
   const vargs: ValidProveCertificateArgs = {
     type: validateOptionalBase64String(args.certificate.type, 'certificate.type'),
@@ -881,7 +878,7 @@ export interface ValidListOutputsArgs extends ValidWalletSignerArgs {
   includeTags: BooleanDefaultFalse
   includeLabels: BooleanDefaultFalse
   limit: PositiveIntegerDefault10Max10000
-  offset: PositiveIntegerOrZero
+  offset: number
   seekPermission: BooleanDefaultTrue
   knownTxids: string[]
 }
@@ -896,14 +893,17 @@ export interface ValidListOutputsArgs extends ValidWalletSignerArgs {
  * @param {BooleanDefaultFalse} [args.includeTags] - Optional. Whether the tags associated with the output should be returned.
  * @param {BooleanDefaultFalse} [args.includeLabels] - Optional. Whether the labels associated with the transaction containing the output should be returned.
  * @param {PositiveIntegerDefault10Max10000} [args.limit] - Optional limit on the number of outputs to return.
- * @param {PositiveIntegerOrZero} [args.offset] - Optional. Number of outputs to skip before starting to return results.
+ * @param {number} [args.offset] - If positive or zero: Number of outputs to skip before starting to return results, oldest first.
+ * If negative: Outputs are returned newest first and offset of -1 is the newest output.
+ * When using negative offsets, caution is required as new outputs may be added between calls,
+ * potentially causing outputs to be duplicated across calls.
  * @param {BooleanDefaultTrue} [args.seekPermission] — Optional. Whether to seek permission from the user for this operation if required. Default true, will return an error rather than proceed if set to false.
  */
 export function validateListOutputsArgs(args: ListOutputsArgs): ValidListOutputsArgs {
   let tagQueryMode: 'any' | 'all'
   if (args.tagQueryMode === undefined || args.tagQueryMode === 'any') tagQueryMode = 'any'
   else if (args.tagQueryMode === 'all') tagQueryMode = 'all'
-  else throw new sdk.WERR_INVALID_PARAMETER('tagQueryMode', `undefined, 'any', or 'all'`)
+  else throw new WERR_INVALID_PARAMETER('tagQueryMode', `undefined, 'any', or 'all'`)
 
   const vargs: ValidListOutputsArgs = {
     basket: validateStringLength(args.basket, 'basket', 1, 300),
@@ -915,7 +915,7 @@ export function validateListOutputsArgs(args: ListOutputsArgs): ValidListOutputs
     includeTags: defaultFalse(args.includeTags),
     includeLabels: defaultFalse(args.includeLabels),
     limit: validateInteger(args.limit, 'limit', 10, 1, 10000),
-    offset: validateInteger(args.offset, 'offset', 0, 0),
+    offset: validateInteger(args.offset, 'offset', 0, undefined, undefined),
     seekPermission: defaultTrue(args.seekPermission),
     knownTxids: []
   }
@@ -954,7 +954,7 @@ export function validateListActionsArgs(args: ListActionsArgs): ValidListActions
   let labelQueryMode: 'any' | 'all'
   if (args.labelQueryMode === undefined || args.labelQueryMode === 'any') labelQueryMode = 'any'
   else if (args.labelQueryMode === 'all') labelQueryMode = 'all'
-  else throw new sdk.WERR_INVALID_PARAMETER('labelQueryMode', `undefined, 'any', or 'all'`)
+  else throw new WERR_INVALID_PARAMETER('labelQueryMode', `undefined, 'any', or 'all'`)
 
   const vargs: ValidListActionsArgs = {
     labels: (args.labels || []).map(t => validateLabel(t)),